@pie-players/pie-default-tool-loaders 0.3.65 → 0.3.67

package/README.md

@@ -8,7 +8,7 @@ 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 four things, all answers to "which capabilities does this deployment have
+It owns five things, all answers to "which capabilities does this deployment have
 and how does the program tier them":
 
 | Export | What it decides |
@@ -22,6 +22,22 @@ and how does the program tier them":
 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
@@ -54,13 +70,19 @@ const registry = createDefaultToolRegistry({
 registerSectionToolModuleLoaders(registry);
 ```
 
-## Accommodations are not in the packaged set
+## 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 capability declaring `requiresAuthoredContent` is absent from
-`PACKAGED_TOOL_REGISTRATIONS` and its support ids from
-`UNIVERSAL_SUPPORTS_PRESET`. 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.
+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";
@@ -94,4 +116,3 @@ 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/content-alternates.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The packaged capabilities that carry an authored alternate and render it as a
+ * region.
+ *
+ * A projection of the composition set below, kept in its own module for one
+ * reason: it must be importable without reaching the packaged composition table,
+ * whose lazy loaders name concrete `pie-tool-*` packages. A renderer that only
+ * ever shows text alternates — print — would otherwise carry a calculator and a
+ * TTS bundle it can never activate.
+ *
+ * Which slot an alternate fills is still the renderer's decision, not this list's:
+ * every entry declares its own `surfaces`, and a host resolves the slots it
+ * actually opens. Print opens the in-flow one and not the docked-media one,
+ * because a signed alternate on paper is a blank rectangle.
+ *
+ * `tests/content-alternates.test.ts` pins this against the composition set in both
+ * directions, so a capability added there cannot quietly fail to reach print.
+ */
+import type { ToolRegistration } from "@pie-players/pie-assessment-toolkit/tools/internal";
+export declare const CONTENT_ALTERNATE_REGISTRATIONS: readonly ToolRegistration[];

package/dist/content-alternates.js

@@ -0,0 +1,22 @@
+/**
+ * The packaged capabilities that carry an authored alternate and render it as a
+ * region.
+ *
+ * A projection of the composition set below, kept in its own module for one
+ * reason: it must be importable without reaching the packaged composition table,
+ * whose lazy loaders name concrete `pie-tool-*` packages. A renderer that only
+ * ever shows text alternates — print — would otherwise carry a calculator and a
+ * TTS bundle it can never activate.
+ *
+ * Which slot an alternate fills is still the renderer's decision, not this list's:
+ * every entry declares its own `surfaces`, and a host resolves the slots it
+ * actually opens. Print opens the in-flow one and not the docked-media one,
+ * because a signed alternate on paper is a blank rectangle.
+ *
+ * `tests/content-alternates.test.ts` pins this against the composition set in both
+ * directions, so a capability added there cannot quietly fail to reach print.
+ */
+import { audioTranscriptRegistration } from "./registrations/audio-transcript.js";
+export const CONTENT_ALTERNATE_REGISTRATIONS = [
+    audioTranscriptRegistration,
+];

package/dist/index.d.ts

@@ -1,27 +1,10 @@
-export { UNIVERSAL_SUPPORTS_PRESET, createUniversalPersonalNeedsProfile, } from "./universal-supports.js";
-export type { PackagedToolRegistryOptions, RegisterPackagedToolsOptions, } from "./packaged-tool-registry.js";
-export { createPackagedToolRegistry, PACKAGED_TOOL_ORDER, PACKAGED_TOOL_REGISTRATIONS, registerPackagedTools, } from "./packaged-tool-registry.js";
-export { PACKAGED_TOOL_TAG_MAP } from "./tool-tag-map.js";
-export { PACKAGED_TOOL_PLACEMENT, SECTION_PLAYER_PREFERRED_TOOL_PLACEMENT, } from "./tool-placement.js";
+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 { CONTENT_ALTERNATE_REGISTRATIONS } from "./content-alternates.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";
-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;

package/dist/index.js

@@ -1,57 +1,13 @@
-export { UNIVERSAL_SUPPORTS_PRESET, createUniversalPersonalNeedsProfile, } from "./universal-supports.js";
-export { createPackagedToolRegistry, PACKAGED_TOOL_ORDER, PACKAGED_TOOL_REGISTRATIONS, registerPackagedTools, } from "./packaged-tool-registry.js";
-export { PACKAGED_TOOL_TAG_MAP } from "./tool-tag-map.js";
-export { PACKAGED_TOOL_PLACEMENT, SECTION_PLAYER_PREFERRED_TOOL_PLACEMENT, } from "./tool-placement.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";
+// The authored-alternate subset, for a renderer that shows alternates and no
+// toolbar — importable without the packaged composition's tool loaders.
+export { CONTENT_ALTERNATE_REGISTRATIONS } from "./content-alternates.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";
-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 || {}),
-    });
-}

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;