@pie-players/pie-assessment-toolkit 0.3.63 → 0.3.65

package/dist/services/spoken-audio-cards.js

@@ -0,0 +1,66 @@
+/**
+ * Recorded audio as a `spoken` catalog card.
+ *
+ * QTI 3 treats a recording and synthesized speech as the *same* support — both
+ * are `spoken`, and a card carries recorded audio through `qti-file-href` plus a
+ * MIME type — so this is not a new accommodation but the other form the existing
+ * one can take. Some programs prefer a human voice to synthesis; PIE's `spoken`
+ * card was string-only, so it had no way to say "play this file for this node".
+ *
+ * A node commonly carries both forms in the same language: the reading script
+ * *and* a recording of it. That is APIP's pattern and what QTI's migration
+ * guidance preserves, because the script is both the source the audio was
+ * generated from and the fallback for when the audio will not play. Resolution
+ * chooses between them with `CatalogLookupOptions.form`; playback treats the
+ * script as the recording's fallback.
+ *
+ * Validation posture matches sign-language cards: "treat as absent, never as
+ * partially valid". A malformed payload must not produce a silent player that
+ * looks like read-aloud is working.
+ *
+ * Part of PIE Assessment Toolkit.
+ */
+import { normalizeMediaFragment, normalizeMediaSources, trimmedOrUndefined, } from "./catalog-media.js";
+/** Catalog type token for spoken alternates. Matches QTI 3's `support` value. */
+export const SPOKEN_CATALOG_TYPE = "spoken";
+/**
+ * Validate a `spoken` card's payload into something playable, or `null`.
+ *
+ * Silent when the card simply is not a recording — a card carrying `content` is
+ * a reading script, which is the overwhelmingly common case and not a fault.
+ * Loud when a card looks like it meant to be a recording and cannot be played,
+ * because that failure is otherwise invisible to everyone but the learner who
+ * needed it.
+ */
+export function resolveSpokenAudioMedia(card) {
+    if (!card)
+        return null;
+    const payload = card.payload;
+    if (!payload || typeof payload !== "object") {
+        // A script card, not a broken audio card. Resolution asks for the payload
+        // form as a *preference*, so getting a `content` card back here is normal.
+        return null;
+    }
+    const media = payload.media;
+    if (!media || typeof media !== "object") {
+        console.warn("[spoken-audio] card carries a `payload` with no `media`; recorded speech needs `media.sources`, so this card is ignored and read-aloud falls back to the script or generated speech");
+        return null;
+    }
+    // A signing video filed under `spoken` is a mis-authored card, not an audio
+    // track to guess at. Refusing it keeps the two card types from quietly
+    // swapping roles.
+    if (media.kind !== undefined && media.kind !== "audio") {
+        console.warn(`[spoken-audio] card's media is kind "${media.kind}", not "audio"; a spoken card carries recorded speech, so this card is ignored`);
+        return null;
+    }
+    const sources = normalizeMediaSources(media.sources);
+    if (sources.length === 0) {
+        console.warn("[spoken-audio] card's `media.sources` yielded no usable URL; read-aloud falls back to the script or generated speech");
+        return null;
+    }
+    return {
+        sources,
+        fragment: normalizeMediaFragment(payload.fragment),
+        label: trimmedOrUndefined(media.label),
+    };
+}

package/dist/services/tool-config-defaults.d.ts

@@ -1,3 +1,10 @@
+/**
+ * Placement defaults this package can hold.
+ *
+ * Only the empty one. `PACKAGED_TOOL_PLACEMENT` and
+ * `SECTION_PLAYER_PREFERRED_TOOL_PLACEMENT` name capabilities, so they moved to
+ * the composition layer (`@pie-players/pie-default-tool-loaders`).
+ */
 export declare const DEFAULT_TOOL_PLACEMENT: {
     readonly assessment: readonly [];
     readonly section: readonly [];
@@ -6,26 +13,3 @@ export declare const DEFAULT_TOOL_PLACEMENT: {
     readonly rubric: readonly [];
     readonly element: readonly [];
 };
-/**
- * Complete placement preset for hosts that want to enable all packaged tools.
- * Prefer explicit host configuration over implicit defaults.
- */
-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"];
-};
-/**
- * Opt-in section-player placement preset for hosts that want to expose every
- * packaged tool once at its normal assessment surface. This is not exhaustive:
- * `supportedLevels` still defines where tools can run, and hosts can still
- * choose different placement for custom UX.
- */
-export declare const SECTION_PLAYER_PREFERRED_TOOL_PLACEMENT: {
-    section: string[];
-    item: string[];
-    passage: string[];
-};

package/dist/services/tool-config-defaults.js

@@ -1,3 +1,10 @@
+/**
+ * Placement defaults this package can hold.
+ *
+ * Only the empty one. `PACKAGED_TOOL_PLACEMENT` and
+ * `SECTION_PLAYER_PREFERRED_TOOL_PLACEMENT` name capabilities, so they moved to
+ * the composition layer (`@pie-players/pie-default-tool-loaders`).
+ */
 export const DEFAULT_TOOL_PLACEMENT = {
     assessment: [],
     section: [],
@@ -6,49 +13,3 @@ export const DEFAULT_TOOL_PLACEMENT = {
     rubric: [],
     element: [],
 };
-/**
- * Complete placement preset for hosts that want to enable all packaged tools.
- * Prefer explicit host configuration over implicit defaults.
- */
-export const PACKAGED_TOOL_PLACEMENT = {
-    assessment: ["theme"],
-    section: ["theme"],
-    item: [
-        "textToSpeech",
-        "highlighter",
-        "annotationToolbar",
-        "graph",
-        "periodicTable",
-    ],
-    passage: ["textToSpeech", "highlighter", "annotationToolbar", "lineReader"],
-    rubric: ["textToSpeech", "highlighter", "annotationToolbar", "lineReader"],
-    element: [
-        "calculator",
-        "answerEliminator",
-        "textToSpeech",
-        "ruler",
-        "protractor",
-        "highlighter",
-        "annotationToolbar",
-        "graph",
-        "periodicTable",
-    ],
-};
-/**
- * Opt-in section-player placement preset for hosts that want to expose every
- * packaged tool once at its normal assessment surface. This is not exhaustive:
- * `supportedLevels` still defines where tools can run, and hosts can still
- * choose different placement for custom UX.
- */
-export const SECTION_PLAYER_PREFERRED_TOOL_PLACEMENT = {
-    section: [
-        "theme",
-        "graph",
-        "periodicTable",
-        "lineReader",
-        "ruler",
-        "protractor",
-    ],
-    item: ["calculator", "textToSpeech", "answerEliminator", "annotationToolbar"],
-    passage: ["textToSpeech", "annotationToolbar"],
-};

package/dist/services/tool-config-validation.d.ts

@@ -4,7 +4,7 @@ import type { ToolRegistry } from "./ToolRegistry.js";
 export type ToolConfigStrictness = "off" | "warn" | "error";
 export type ToolConfigDiagnosticSeverity = "warning" | "error";
 export interface ToolConfigDiagnostic {
-    code: "tools.unknownToolId" | "tools.unsupportedLevel" | "tools.unknownProviderKey" | "tools.removedProviderKey" | "tools.providerSanitizeFailed" | "tools.providerValidateFailed" | "tools.invalidProviderValidation";
+    code: "tools.unknownToolId" | "tools.unsupportedLevel" | "tools.unplaceableActivation" | "tools.registryUnavailable" | "tools.unknownProviderKey" | "tools.removedProviderKey" | "tools.providerSanitizeFailed" | "tools.providerValidateFailed" | "tools.invalidProviderValidation";
     severity: ToolConfigDiagnosticSeverity;
     path: string;
     message: string;

package/dist/services/tool-config-validation.js

@@ -1,6 +1,5 @@
 import { normalizeToolsConfig, } from "./tools-config-normalizer.js";
 import { frameworkErrorFromToolConfigDiagnostics, frameworkErrorFromUnknown, } from "./framework-error.js";
-import { createPackagedToolRegistry } from "./createDefaultToolRegistry.js";
 export function frameworkErrorFromToolConfigValidation(args) {
     if (Array.isArray(args.diagnostics) && args.diagnostics.length > 0) {
         return frameworkErrorFromToolConfigDiagnostics({
@@ -120,6 +119,20 @@ function collectPlacementDiagnostics(config, toolMap, diagnostics) {
                 }));
                 continue;
             }
+            if (tool.activation === "region") {
+                // A region capability has no toolbar button, so placing it names a
+                // surface that will never render it. Reported at the placement rather
+                // than at render time, where the symptom is an absent accommodation and
+                // no error.
+                diagnostics.push(createDiagnostic({
+                    code: "tools.unplaceableActivation",
+                    severity: "error",
+                    path: `placement.${level}`,
+                    message: `Tool "${toolId}" renders into a host surface (activation "region") and cannot be placed on the ${level} toolbar. Remove it from placement.${level}; its availability comes from policy plus its content dependency.`,
+                    toolId,
+                }));
+                continue;
+            }
             const supportsLevel = tool.supportedLevels.includes(level);
             // Leniency policy: section-capable tools are tolerated in item placement.
             // This avoids strict failures for common host config patterns while still
@@ -204,9 +217,27 @@ function throwValidationError(diagnostics, source) {
 export function normalizeAndValidateToolsConfig(input, options = {}) {
     const strictness = normalizeToolConfigStrictness(options.strictness);
     const source = options.source ?? "tools";
-    const registryTools = getRegistryToolMap(options.toolRegistry ?? createPackagedToolRegistry());
+    const registryTools = getRegistryToolMap(options.toolRegistry);
     const normalized = normalizeToolsConfig(input);
     const diagnostics = [];
+    // Tool-id and provider checks need a registry to check against, and every
+    // collector below returns early without one. Say so: this package no longer
+    // falls back to a packaged registry, so a caller that used to get id
+    // validation for free now gets none, and a silent downgrade from "your ids are
+    // valid" to "nobody looked" is the kind of change that surfaces as a typo
+    // reaching a learner.
+    const hasConfiguredTools = Object.values(normalized.placement).some((ids) => ids.length > 0) ||
+        Object.keys(normalized.providers).length > 0 ||
+        (normalized.policy.allowed?.length ?? 0) > 0 ||
+        (normalized.policy.blocked?.length ?? 0) > 0;
+    if (registryTools.size === 0 && hasConfiguredTools) {
+        diagnostics.push(createDiagnostic({
+            code: "tools.registryUnavailable",
+            severity: "warning",
+            path: "tools",
+            message: 'No tool registry was supplied, so tool ids, placement levels and provider config were not validated. Pass `toolRegistry` — for the packaged capability set, `createPackagedToolRegistry()` from "@pie-players/pie-default-tool-loaders".',
+        }));
+    }
     const hasRemovedTtsKey = Object.hasOwn(normalized.providers, "tts");
     const nextProviders = {
         ...(normalized.providers || {}),
@@ -233,8 +264,17 @@ export function normalizeAndValidateToolsConfig(input, options = {}) {
     if (strictness === "warn") {
         emitWarnings(diagnostics, source);
     }
-    if (strictness === "error" && diagnostics.length > 0) {
-        throwValidationError(diagnostics, source);
+    // Severity decides what `strictness: "error"` rejects. Every diagnostic this
+    // function raised was `"error"` until `tools.registryUnavailable`, which
+    // reports that validation could not run rather than that the config is wrong —
+    // throwing on it would turn "no registry supplied" from a host's existing,
+    // working setup into a construction failure.
+    const blocking = diagnostics.filter((entry) => entry.severity === "error");
+    if (strictness === "error" && blocking.length > 0) {
+        throwValidationError(blocking, source);
+    }
+    if (strictness === "error" && blocking.length === 0) {
+        emitWarnings(diagnostics, source);
     }
     return {
         config: nextConfig,

package/dist/services/tts/browser-provider.js

@@ -26,7 +26,8 @@ const findBrowserVoice = (voices, preferredName) => {
     const languagePrefix = language.split("-")[0] || "en";
     const matchesLanguage = (voice) => {
         const voiceLanguage = normalizeLanguageCode(voice.lang);
-        return voiceLanguage === language || voiceLanguage.startsWith(`${languagePrefix}-`);
+        return (voiceLanguage === language ||
+            voiceLanguage.startsWith(`${languagePrefix}-`));
     };
     const ranked = [
         (voice) => voice.localService && matchesLanguage(voice),

package/dist/services/tts/math-aware-text-processing.js

@@ -1,5 +1,5 @@
 import { canonicalizeMathML } from "./mathml-sanitization.js";
-import { collectVisibleTextAndMap, isNodeHiddenForTTS, normalizeTextForSpeech, shouldInsertWordBoundarySpace, } from "./text-processing.js";
+import { collectVisibleTextAndMap, isNodeExcludedFromSpeech, normalizeTextForSpeech, shouldInsertWordBoundarySpace, } from "./text-processing.js";
 const createAccumulator = (options) => ({
     chars: [],
     map: new Map(),
@@ -226,7 +226,7 @@ const textFallbackFromMathML = (mathml) => {
 const collectVisibleMathFallback = (element, canonicalMathML, options) => {
     const mathAcc = createAccumulator(options);
     const visit = (node) => {
-        if (isNodeHiddenForTTS(node, element))
+        if (isNodeExcludedFromSpeech(node, element))
             return;
         if (node.nodeType === 3) {
             appendTextNode(mathAcc, node);
@@ -284,7 +284,7 @@ const collectMathAware = (root, options) => {
         textChunkSourceElement = undefined;
     };
     const processNode = (node) => {
-        if (isNodeHiddenForTTS(node, root))
+        if (isNodeExcludedFromSpeech(node, root))
             return;
         if (node.nodeType === Node.TEXT_NODE) {
             const sourceElement = resolveTextChunkSourceElement(node, root);

package/dist/services/tts/text-processing.d.ts

@@ -11,6 +11,57 @@ export declare const normalizeTextForSpeech: (text: string) => string;
 export declare const createSpeechAlignmentTokenPattern: () => RegExp;
 export declare const isElementHiddenForTTS: (element: Element) => boolean;
 export declare const isNodeHiddenForTTS: (node: Node, root?: Element | null) => boolean;
+/**
+ * Marks content that must be shown but never spoken — items where reading *is*
+ * the construct, such as decoding and spelling, where speaking the node hands
+ * over the answer.
+ *
+ * Not a PNP field: `prohibitedSupports` is the learner declining a support, while
+ * this is the item saying "not here, for anyone", so it overrides an entitlement
+ * rather than yielding to it.
+ *
+ * Shape follows QTI 3's `data-qti-suppress-tts` — an attribute on the content
+ * element, single-valued, vocabulary below. Element placement is what makes it
+ * work on undocked nodes and enforceable in the selection read-aloud path, which
+ * consults no catalog. The name follows PIE's `data-tts-*` family, and PIE reads
+ * only this spelling; importers map QTI's.
+ */
+export declare const TTS_SUPPRESS_ATTRIBUTE = "data-tts-suppress";
+/**
+ * Whether this element forbids machine read-aloud of itself and its subtree.
+ *
+ * Unrecognized and empty values suppress rather than pass through, and say so once
+ * per distinct value: a typo that fell through would speak a word the item was
+ * measuring, invalidating the score with no visible symptom, whereas
+ * over-suppressing only withholds speech an author had already marked as withheld.
+ */
+export declare const isElementSuppressedForTTS: (element: Element) => boolean;
+export declare const isNodeSuppressedForTTS: (node: Node, root?: Element | null) => boolean;
+/**
+ * The predicate every speech-producing path filters on: hidden *or* suppressed.
+ *
+ * Kept distinct from `isNodeHiddenForTTS`, which stays a question about
+ * visibility — suppressed content is visible on purpose, and the highlight
+ * geometry resolvers that ask "can the candidate see this" must keep getting
+ * the visibility answer rather than this one.
+ */
+export declare const isNodeExcludedFromSpeech: (node: Node, root?: Element | null) => boolean;
+/**
+ * Text of a range with the parts that must not be spoken removed.
+ *
+ * `Range.toString()` is not usable for speech: it is pure character extraction
+ * and honours no DOM filter at all, so it happily returns suppressed — and
+ * hidden — text. The selection read-aloud path is a text-in path rather than a
+ * DOM walk, which makes this the only place its content can be filtered.
+ *
+ * `filtered` reports whether anything was dropped, so a caller can tell "the
+ * candidate selected nothing speakable" apart from "the candidate selected
+ * nothing".
+ */
+export declare const collectRangeTextForSpeech: (range: Range, root: Element) => {
+    text: string;
+    filtered: boolean;
+};
 export declare const shouldInsertWordBoundarySpace: (previousChar: string | null, nextChar: string | null, options?: TextProcessingOptions) => boolean;
 export declare const collectVisibleTextAndMap: (element: Element, options?: TextProcessingOptions) => {
     text: string;

package/dist/services/tts/text-processing.js

@@ -62,6 +62,122 @@ export const isNodeHiddenForTTS = (node, root) => {
     }
     return false;
 };
+/**
+ * Marks content that must be shown but never spoken — items where reading *is*
+ * the construct, such as decoding and spelling, where speaking the node hands
+ * over the answer.
+ *
+ * Not a PNP field: `prohibitedSupports` is the learner declining a support, while
+ * this is the item saying "not here, for anyone", so it overrides an entitlement
+ * rather than yielding to it.
+ *
+ * Shape follows QTI 3's `data-qti-suppress-tts` — an attribute on the content
+ * element, single-valued, vocabulary below. Element placement is what makes it
+ * work on undocked nodes and enforceable in the selection read-aloud path, which
+ * consults no catalog. The name follows PIE's `data-tts-*` family, and PIE reads
+ * only this spelling; importers map QTI's.
+ */
+export const TTS_SUPPRESS_ATTRIBUTE = "data-tts-suppress";
+const SUPPRESSES_COMPUTER_READ_ALOUD = new Set(["computer-read-aloud", "all"]);
+// `screen-reader` is in the vocabulary but is not ours: it asks the delivery
+// engine to hide the node from assistive technology, which is the host's job
+// (and is what `aria-hidden` above already covers on the way in). A node marked
+// only `screen-reader` is still legitimately machine-read aloud.
+const SUPPRESS_VALUES = new Set([
+    ...SUPPRESSES_COMPUTER_READ_ALOUD,
+    "screen-reader",
+]);
+const warnedSuppressValues = new Set();
+/**
+ * Whether this element forbids machine read-aloud of itself and its subtree.
+ *
+ * Unrecognized and empty values suppress rather than pass through, and say so once
+ * per distinct value: a typo that fell through would speak a word the item was
+ * measuring, invalidating the score with no visible symptom, whereas
+ * over-suppressing only withholds speech an author had already marked as withheld.
+ */
+export const isElementSuppressedForTTS = (element) => {
+    const raw = element.getAttribute?.(TTS_SUPPRESS_ATTRIBUTE);
+    if (raw === null || raw === undefined)
+        return false;
+    const value = raw.trim().toLowerCase();
+    if (SUPPRESSES_COMPUTER_READ_ALOUD.has(value))
+        return true;
+    if (SUPPRESS_VALUES.has(value))
+        return false;
+    if (!warnedSuppressValues.has(value)) {
+        warnedSuppressValues.add(value);
+        console.warn(`[tts] ${TTS_SUPPRESS_ATTRIBUTE}="${raw}" is not one of ${Array.from(SUPPRESS_VALUES).join(", ")}; suppressing read-aloud for this content anyway, because a suppression attribute that fails open would leak the answer to items where reading is the construct. Correct the value to silence this.`);
+    }
+    return true;
+};
+export const isNodeSuppressedForTTS = (node, root) => {
+    let current = node.nodeType === 1
+        ? node
+        : node.parentElement;
+    while (current) {
+        if (isElementSuppressedForTTS(current))
+            return true;
+        if (root && current === root)
+            break;
+        current = current.parentElement;
+    }
+    return false;
+};
+/**
+ * The predicate every speech-producing path filters on: hidden *or* suppressed.
+ *
+ * Kept distinct from `isNodeHiddenForTTS`, which stays a question about
+ * visibility — suppressed content is visible on purpose, and the highlight
+ * geometry resolvers that ask "can the candidate see this" must keep getting
+ * the visibility answer rather than this one.
+ */
+export const isNodeExcludedFromSpeech = (node, root) => isNodeHiddenForTTS(node, root) || isNodeSuppressedForTTS(node);
+/**
+ * Text of a range with the parts that must not be spoken removed.
+ *
+ * `Range.toString()` is not usable for speech: it is pure character extraction
+ * and honours no DOM filter at all, so it happily returns suppressed — and
+ * hidden — text. The selection read-aloud path is a text-in path rather than a
+ * DOM walk, which makes this the only place its content can be filtered.
+ *
+ * `filtered` reports whether anything was dropped, so a caller can tell "the
+ * candidate selected nothing speakable" apart from "the candidate selected
+ * nothing".
+ */
+export const collectRangeTextForSpeech = (range, root) => {
+    if (typeof document === "undefined" ||
+        typeof document.createTreeWalker !==
+            "function" ||
+        typeof NodeFilter === "undefined" ||
+        typeof range.intersectsNode !== "function") {
+        // Degraded, and deliberately not silent about the difference: callers still
+        // enforce whole-selection suppression from the range's common ancestor, so
+        // the construct guard holds even here. What is lost is per-node filtering
+        // of a selection that only partly overlaps suppressed content.
+        return { text: range.toString(), filtered: false };
+    }
+    const parts = [];
+    let filtered = false;
+    const walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT);
+    let current = walker.nextNode();
+    while (current) {
+        const textNode = current;
+        if (range.intersectsNode(textNode)) {
+            if (isNodeExcludedFromSpeech(textNode, root)) {
+                filtered = true;
+            }
+            else {
+                const raw = textNode.textContent || "";
+                const start = textNode === range.startContainer ? range.startOffset : 0;
+                const end = textNode === range.endContainer ? range.endOffset : raw.length;
+                parts.push(raw.slice(start, end));
+            }
+        }
+        current = walker.nextNode();
+    }
+    return { text: parts.join(""), filtered };
+};
 export const shouldInsertWordBoundarySpace = (previousChar, nextChar, options) => {
     if (!previousChar || !nextChar)
         return false;
@@ -111,7 +227,7 @@ export const collectVisibleTextAndMap = (element, options) => {
     while (current) {
         const textNode = current;
         const parent = textNode.parentElement;
-        if (parent && !isNodeHiddenForTTS(textNode, element)) {
+        if (parent && !isNodeExcludedFromSpeech(textNode, element)) {
             const raw = textNode.textContent || "";
             const firstVisibleMatch = raw.match(/\S/);
             const firstVisibleChar = firstVisibleMatch ? firstVisibleMatch[0] : null;

package/dist/services/tts-runtime-config.js

@@ -117,7 +117,11 @@ export const normalizeTTSSpeedControlOptions = (value) => {
         if (rate === undefined || dedupedRates.has(rate))
             continue;
         dedupedRates.add(rate);
-        const defaultLabel = rate === 1 ? "Normal" : typeof entry === "number" ? formatSpeedLabel(rate) : formatSpeedLabel(rate);
+        const defaultLabel = rate === 1
+            ? "Normal"
+            : typeof entry === "number"
+                ? formatSpeedLabel(rate)
+                : formatSpeedLabel(rate);
         const label = typeof entry === "number"
             ? defaultLabel
             : trimOptionalText(record.label) || defaultLabel;
@@ -131,7 +135,8 @@ export const normalizeTTSSpeedControlOptions = (value) => {
             label,
             ariaLabel,
             isDefault: false,
-            requestedDefault: record.default === true || record.isDefault === true,
+            requestedDefault: record.default === true ||
+                record.isDefault === true,
         });
     }
     if (!normalized.length) {

package/dist/tools/internal.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Registration-authoring surface.
+ *
+ * What a package outside this one needs to write a `ToolRegistration`: the
+ * registration types, the context predicates a tool answers `isVisibleInContext`
+ * with, scoped-id and element-creation helpers, the toolbar button/overlay
+ * helpers, and the provider descriptors for the two capabilities that ship a
+ * provider.
+ *
+ * A separate entry point rather than additions to `.` for the same reason
+ * `runtime/internal` and `policy/internal` exist: this is a surface for sibling
+ * packages in this repo, not a contract offered to hosts. Widening `.` with two
+ * dozen registration-authoring helpers would make every one of them something a
+ * host could reasonably expect us to keep.
+ *
+ * It exists because the packaged registrations moved out to the composition layer
+ * (`@pie-players/pie-default-tool-loaders`) so core stops naming capabilities.
+ * A host writing its own capability package imports from here too, which is the
+ * point — the mechanism is the same one our own registrations use.
+ */
+export type { HostedToolContext, HostedToolSize, ResolvedToolContext, ToolActivation, ToolContentDependency, ToolContentDependencyContext, ToolModuleLoader, ToolProviderDescriptor, ToolRegistration, ToolRenderElement, ToolSingletonScope, ToolSurfaceRenderContext, ToolSurfaceRenderResult, ToolSurfaceServices, ToolToolbarButtonDefinition, ToolToolbarRenderResult, ToolWindowShellConfig, ToolbarContext, } from "../services/ToolRegistry.js";
+export { ToolRegistry } from "../services/ToolRegistry.js";
+export type { ToolContext, ToolLevel } from "../services/tool-context.js";
+export { hasChoiceInteraction, hasMathContent, hasReadableText, hasScienceContent, } from "../services/tool-context.js";
+export { createScopedToolId } from "../services/tool-instance-id.js";
+export type { ToolComponentFactory, ToolComponentFactoryMap, ToolComponentOverrides, ToolTagMap, } from "./tool-tag-map.js";
+export { createToolElement, resolveToolTag, toToolIdFromTag, } from "./tool-tag-map.js";
+export { applyOverlaySurface, createScopedVisibilityBinding, syncButtonAndOverlayVisibility, } from "./registrations/toolbar-registration-helpers.js";
+export type { ElementToolStateStoreApi, ToolCoordinatorApi, ToolkitCoordinatorApi, TtsServiceApi, } from "../services/interfaces.js";
+export type { ToolPlacementConfig, ToolProviderConfig, } from "../services/tools-config-normalizer.js";
+export type { ToolConfigDiagnostic } from "../services/tool-config-validation.js";
+export { DesmosToolProvider, TTSToolProvider, } from "../services/tool-providers/index.js";
+export type { NormalizedTTSSpeedOption } from "../services/tts-runtime-config.js";
+export { buildRuntimeTTSConfig, normalizeTTSLayoutMode, normalizeTTSSpeedControlOptions, resolveRuntimeProvider, resolveTTSBackend, resolveTTSHostToolbarLayout, resolveTTSLayoutMode, resolveTTSRuntimeSettings, resolveTransportMode, } from "../services/tts-runtime-config.js";

package/dist/tools/internal.js

@@ -0,0 +1,33 @@
+/**
+ * Registration-authoring surface.
+ *
+ * What a package outside this one needs to write a `ToolRegistration`: the
+ * registration types, the context predicates a tool answers `isVisibleInContext`
+ * with, scoped-id and element-creation helpers, the toolbar button/overlay
+ * helpers, and the provider descriptors for the two capabilities that ship a
+ * provider.
+ *
+ * A separate entry point rather than additions to `.` for the same reason
+ * `runtime/internal` and `policy/internal` exist: this is a surface for sibling
+ * packages in this repo, not a contract offered to hosts. Widening `.` with two
+ * dozen registration-authoring helpers would make every one of them something a
+ * host could reasonably expect us to keep.
+ *
+ * It exists because the packaged registrations moved out to the composition layer
+ * (`@pie-players/pie-default-tool-loaders`) so core stops naming capabilities.
+ * A host writing its own capability package imports from here too, which is the
+ * point — the mechanism is the same one our own registrations use.
+ */
+export { ToolRegistry } from "../services/ToolRegistry.js";
+export { hasChoiceInteraction, hasMathContent, hasReadableText, hasScienceContent, } from "../services/tool-context.js";
+// Scoped tool instance ids, so two placements of one tool do not share state.
+export { createScopedToolId } from "../services/tool-instance-id.js";
+export { createToolElement, resolveToolTag, toToolIdFromTag, } from "./tool-tag-map.js";
+// Toolbar button/overlay wiring shared by every toolbar-toggle registration.
+export { applyOverlaySurface, createScopedVisibilityBinding, syncButtonAndOverlayVisibility, } from "./registrations/toolbar-registration-helpers.js";
+// Provider descriptors for the two packaged capabilities that ship one. These
+// stay here rather than moving with the registrations because they are written
+// against the `pie-calculator` and `pie-tts` contract packages, which the
+// toolkit's own `TTSService` and provider registry also depend on.
+export { DesmosToolProvider, TTSToolProvider, } from "../services/tool-providers/index.js";
+export { buildRuntimeTTSConfig, normalizeTTSLayoutMode, normalizeTTSSpeedControlOptions, resolveRuntimeProvider, resolveTTSBackend, resolveTTSHostToolbarLayout, resolveTTSLayoutMode, resolveTTSRuntimeSettings, resolveTransportMode, } from "../services/tts-runtime-config.js";

package/dist/tools/tool-tag-map.d.ts

@@ -14,10 +14,22 @@ export interface ToolComponentOverrides {
     toolComponentFactories?: Partial<ToolComponentFactoryMap>;
 }
 /**
- * Canonical default web component tag mapping for toolkit tools.
- * Integrators can override any entry via ToolComponentOverrides.
+ * Resolve the element tag for a tool from the overrides in play.
+ *
+ * There is no built-in map to fall back to. One lived here, naming eleven
+ * capabilities, and a core module holding that catalogue is why a host could not
+ * add a twelfth without editing this package — the map was overridable, but the
+ * default was core-resident. The packaged map is `PACKAGED_TOOL_TAG_MAP` in
+ * `@pie-players/pie-default-tool-loaders`, installed onto a registry through
+ * `ToolRegistry.setComponentOverrides`.
+ *
+ * An unmapped toolId falls through to itself, which is only a valid tag if the
+ * host's tool id already looks like one. Every packaged id is a single camelCase
+ * word, so in practice an unmapped packaged tool throws here rather than
+ * rendering a bogus element — the failure names the missing mapping, because
+ * "custom element names must include a hyphen" is a true statement about the
+ * wrong thing.
  */
-export declare const DEFAULT_TOOL_TAG_MAP: ToolTagMap;
 export declare const resolveToolTag: (toolId: string, overrides?: ToolComponentOverrides) => string;
 export declare const createToolElement: (toolId: string, context: ToolContext, toolbarContext: ToolbarContext, overrides?: ToolComponentOverrides) => HTMLElement;
 export declare const toToolIdFromTag: (tagName: string, overrides?: ToolComponentOverrides) => string | undefined;

package/dist/tools/tool-tag-map.js

@@ -1,24 +1,27 @@
 import { validateCustomElementTag } from "@pie-players/pie-players-shared/pie/tag-names";
 /**
- * Canonical default web component tag mapping for toolkit tools.
- * Integrators can override any entry via ToolComponentOverrides.
+ * Resolve the element tag for a tool from the overrides in play.
+ *
+ * There is no built-in map to fall back to. One lived here, naming eleven
+ * capabilities, and a core module holding that catalogue is why a host could not
+ * add a twelfth without editing this package — the map was overridable, but the
+ * default was core-resident. The packaged map is `PACKAGED_TOOL_TAG_MAP` in
+ * `@pie-players/pie-default-tool-loaders`, installed onto a registry through
+ * `ToolRegistry.setComponentOverrides`.
+ *
+ * An unmapped toolId falls through to itself, which is only a valid tag if the
+ * host's tool id already looks like one. Every packaged id is a single camelCase
+ * word, so in practice an unmapped packaged tool throws here rather than
+ * rendering a bogus element — the failure names the missing mapping, because
+ * "custom element names must include a hyphen" is a true statement about the
+ * wrong thing.
  */
-export const DEFAULT_TOOL_TAG_MAP = {
-    calculator: "pie-tool-calculator",
-    textToSpeech: "pie-tool-text-to-speech",
-    ruler: "pie-tool-ruler",
-    protractor: "pie-tool-protractor",
-    answerEliminator: "pie-tool-answer-eliminator",
-    highlighter: "pie-tool-annotation-toolbar",
-    lineReader: "pie-tool-line-reader",
-    theme: "pie-tool-theme",
-    annotationToolbar: "pie-tool-annotation-toolbar",
-    graph: "pie-tool-graph",
-    periodicTable: "pie-tool-periodic-table",
-};
 export const resolveToolTag = (toolId, overrides) => {
-    const mapped = overrides?.toolTagMap?.[toolId] ?? DEFAULT_TOOL_TAG_MAP[toolId] ?? toolId;
-    return validateCustomElementTag(mapped, `tool component tag for "${toolId}"`);
+    const mapped = overrides?.toolTagMap?.[toolId];
+    if (mapped === undefined && !toolId.includes("-")) {
+        throw new Error(`No element tag is mapped for tool "${toolId}". Install a tag map on the registry via setComponentOverrides({ toolTagMap }) — for the packaged capabilities, PACKAGED_TOOL_TAG_MAP from "@pie-players/pie-default-tool-loaders".`);
+    }
+    return validateCustomElementTag(mapped ?? toolId, `tool component tag for "${toolId}"`);
 };
 const createDefaultToolElement = (tagName) => document.createElement(tagName);
 export const createToolElement = (toolId, context, toolbarContext, overrides) => {
@@ -31,6 +34,6 @@ export const createToolElement = (toolId, context, toolbarContext, overrides) =>
 };
 export const toToolIdFromTag = (tagName, overrides) => {
     const validTag = validateCustomElementTag(tagName, "tool component tag");
-    const map = { ...DEFAULT_TOOL_TAG_MAP, ...overrides?.toolTagMap };
+    const map = overrides?.toolTagMap ?? {};
     return Object.entries(map).find(([, tag]) => tag === validTag)?.[0];
 };