@pie-players/pie-assessment-toolkit 0.3.74 → 1.0.0-beta.0

package/dist/services/tts-runtime-config.d.ts

@@ -1,9 +1,9 @@
-import type { TTSConfig } from "./TTSService.js";
-import type { TextToSpeechToolProviderConfig } from "./tools-config-normalizer.js";
+import type { SpeedRateBucket } from "@pie-players/pie-tts";
+import type { TextToSpeechToolProviderConfig, ToolProviderConfig } from "./tools-config-normalizer.js";
 import { type SREMathSpeechOptions } from "./tts/math-speech.js";
+import type { ToolkitTTSConfig } from "./tts/provider-options.js";
 export type TTSLayoutMode = "reserved-row" | "expanding-row" | "floating-overlay" | "left-aligned";
 export interface TTSHostToolbarLayout {
-    mount: "before-buttons";
     controlsRow: {
         reserveSpace: boolean;
         expandWhenToolActive: boolean;
@@ -26,9 +26,10 @@ export interface NormalizedTTSSpeedOption {
     isDefault: boolean;
 }
 export interface TTSRuntimeSettings {
-    backend?: "browser" | "polly" | "google" | "server";
+    /** `browser` speaks through the Web Speech API; `server` through a TTS server. */
+    backend?: "browser" | "server";
+    /** The service behind a `server` backend. */
     serverProvider?: "polly" | "google" | "custom";
-    provider?: "polly" | "google" | "custom";
     engine?: "standard" | "neural";
     sampleRate?: number;
     format?: "mp3" | "ogg" | "pcm";
@@ -37,9 +38,23 @@ export interface TTSRuntimeSettings {
     rate?: number;
     pitch?: number;
     apiEndpoint?: string;
+    /**
+     * The host's locale, used for a read whose content names no language: it
+     * drives text normalization and segmentation, is sent as `language` on the
+     * `pie` transport and as `lang_id` on the `custom` transport when nothing
+     * names a language, and a server given no voice picks one for it. The
+     * content language a read resolves (markup `lang`, the tool's `language`,
+     * the toolkit's `content-language`, then `lang_id`) wins over it.
+     * `docs/architecture/internationalization.md#tts-language` is the contract.
+     */
     language?: string;
     transportMode?: "pie" | "custom";
     endpointMode?: "synthesizePath" | "rootPost";
+    /**
+     * The probe the server provider runs before it reports ready: `voices` reads
+     * the voices route, `endpoint` sends OPTIONS to the synthesis route, `none`
+     * probes nothing. Defaults to `voices` on a `server` backend.
+     */
     endpointValidationMode?: "voices" | "endpoint" | "none";
     includeAuthOnAssetFetch?: boolean;
     /** Origins trusted with the `Authorization` header on asset fetches. */
@@ -48,9 +63,19 @@ export interface TTSRuntimeSettings {
     credentials?: "omit" | "same-origin" | "include";
     /** Headers sent with every request to the TTS server. */
     headers?: Record<string, string>;
-    validateEndpoint?: boolean;
+    /** Server-side caching, sent on the `custom` transport. */
     cache?: boolean;
-    speedRate?: "slow" | "medium" | "fast";
+    /**
+     * Speed bucket sent on the `custom` transport; derived from `rate` when
+     * unset.
+     */
+    speedRate?: SpeedRateBucket;
+    /**
+     * The custom transport's locale, sent on every read in place of the content
+     * language. Where markup and the tool name no language it is also the read's
+     * content language, so text processing and catalog lookups follow it. Leave
+     * it unset to let content language reach the service.
+     */
     lang_id?: string;
     /**
      * Optional inline TTS speed buttons.
@@ -84,21 +109,16 @@ export interface TTSRuntimeSettings {
     /**
      * Options passed through to the provider. The fields derived from the
      * settings above, such as `locale` and the Polly engine, win over these.
+     * The `custom` transport reads the three typed keys; the settings of the
+     * same names win over them.
      */
-    providerOptions?: Record<string, unknown>;
+    providerOptions?: {
+        speedRate?: SpeedRateBucket;
+        lang_id?: string;
+        cache?: boolean;
+        [option: string]: unknown;
+    };
 }
-export declare const normalizeTTSLayoutMode: (value: unknown, fallback?: TTSLayoutMode) => TTSLayoutMode;
-/** Legacy numeric helper defaults. Rendered controls add visible Normal separately. */
-export declare const DEFAULT_TTS_SPEED_OPTIONS: readonly number[];
-export declare const normalizeTTSSpeedOptionConfigs: (value: unknown) => TTSSpeedOption[];
-/**
- * Resolves inline toolbar speed options from host config.
- * - Omitted/non-array: default speed buttons.
- * - Empty array: hide speed buttons.
- * - Arrays that sanitize to no valid values: default speed buttons.
- * - 1.0× is never shown as a discrete speed button.
- */
-export declare const normalizeTTSSpeedOptions: (value: unknown) => number[];
 export declare const normalizeTTSSpeedControlOptions: (value: unknown) => NormalizedTTSSpeedOption[];
 export declare const formatTTSSpeedOptionsAsText: (values: number[]) => string;
 /**
@@ -107,17 +127,25 @@ export declare const formatTTSSpeedOptionsAsText: (values: number[]) => string;
  * - Non-empty text with no parseable finite numbers → same as invalid-only array config: defaults.
  */
 export declare const parseTTSSpeedOptionsFromText: (text: string) => number[];
-export declare const resolveTTSRuntimeSettings: (config: TextToSpeechToolProviderConfig | TTSRuntimeSettings | undefined) => TTSRuntimeSettings;
+/**
+ * The runtime settings of a `textToSpeech` provider entry: its top-level keys
+ * with defaults applied, an unknown `layoutMode` resolved to `left-aligned`.
+ * `enabled` and the runtime `provider` object belong to the tool registration
+ * and are dropped.
+ */
+export declare const resolveTTSRuntimeSettings: (config: TextToSpeechToolProviderConfig | ToolProviderConfig | TTSRuntimeSettings | undefined) => TTSRuntimeSettings & {
+    layoutMode: TTSLayoutMode;
+};
 export declare const resolveTTSBackend: (config: TTSRuntimeSettings) => NonNullable<TTSRuntimeSettings["backend"]>;
-export declare const resolveRuntimeProvider: (config: TTSRuntimeSettings, backend: NonNullable<TTSRuntimeSettings["backend"]>) => TTSRuntimeSettings["serverProvider"];
-export declare const resolveTransportMode: (config: TTSRuntimeSettings, runtimeProvider: TTSRuntimeSettings["serverProvider"]) => NonNullable<TTSRuntimeSettings["transportMode"]>;
 /**
  * The provider configuration built from host settings: the contract's portable
  * fields plus the server adapter's, under the adapter's names.
  */
-export type RuntimeTTSConfig = Pick<TTSConfig, "voice" | "rate" | "pitch" | "providerOptions" | "mathTokenHighlighting"> & Pick<TTSRuntimeSettings, "apiEndpoint" | "language" | "transportMode" | "endpointMode" | "endpointValidationMode" | "includeAuthOnAssetFetch" | "assetOrigins" | "credentials" | "headers" | "validateEndpoint"> & {
+export type RuntimeTTSConfig = Pick<ToolkitTTSConfig, "voice" | "rate" | "pitch" | "providerOptions" | "mathTokenHighlighting"> & Pick<TTSRuntimeSettings, "apiEndpoint" | "language" | "transportMode" | "endpointMode" | "endpointValidationMode" | "includeAuthOnAssetFetch" | "assetOrigins" | "credentials" | "headers"> & {
     provider?: TTSRuntimeSettings["serverProvider"];
 };
 export declare const buildRuntimeTTSConfig: (config: TTSRuntimeSettings) => RuntimeTTSConfig;
-export declare const resolveTTSLayoutMode: (config: TTSRuntimeSettings) => TTSLayoutMode;
-export declare const resolveTTSHostToolbarLayout: (config: TTSRuntimeSettings) => TTSHostToolbarLayout;
+/** The toolbar layout hints for the layout mode of resolved settings. */
+export declare const resolveTTSHostToolbarLayout: (config: {
+    layoutMode: TTSLayoutMode;
+}) => TTSHostToolbarLayout;

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

@@ -6,26 +6,20 @@ const VALID_TTS_LAYOUT_MODES = new Set([
     "left-aligned",
 ]);
 const toRecord = (value) => value && typeof value === "object" ? value : {};
-const isServerBackend = (backend) => backend === "polly" || backend === "google" || backend === "server";
 const withDefault = (value, fallback) => value === undefined ? fallback : value;
-export const normalizeTTSLayoutMode = (value, fallback = "left-aligned") => typeof value === "string" &&
+/** A custom server provider speaks the custom transport, as `ServerTTSProvider` does on its own. */
+const defaultTransportMode = (config) => resolveTTSBackend(config) === "server" && config.serverProvider === "custom"
+    ? "custom"
+    : "pie";
+const normalizeTTSLayoutMode = (value) => typeof value === "string" &&
     VALID_TTS_LAYOUT_MODES.has(value)
     ? value
-    : fallback;
-/** Legacy numeric helper defaults. Rendered controls add visible Normal separately. */
-export const DEFAULT_TTS_SPEED_OPTIONS = Object.freeze([0.8, 1.25]);
+    : "left-aligned";
 const DEFAULT_TTS_SPEED_CONTROL_OPTIONS = Object.freeze([
     { rate: 0.8, label: "Slow", ariaLabel: "Slow speed" },
     { rate: 1, label: "Normal", ariaLabel: "Normal speed", default: true },
     { rate: 1.25, label: "Fast", ariaLabel: "Fast speed" },
 ]);
-const normalizeSpeedRate = (entry) => {
-    if (typeof entry !== "number" || !Number.isFinite(entry) || entry <= 0) {
-        return undefined;
-    }
-    const rounded = Math.round(entry * 100) / 100;
-    return rounded === 1 ? undefined : rounded;
-};
 const normalizeControlSpeedRate = (entry) => {
     if (typeof entry !== "number" || !Number.isFinite(entry) || entry <= 0) {
         return undefined;
@@ -51,56 +45,6 @@ const normalizeSpeedAriaLabel = (label, ariaLabel, usedDefaultLabel) => {
         return ariaLabel;
     return `${label} ${ariaLabel}`;
 };
-const normalizeTTSSpeedOptionConfig = (entry) => {
-    if (typeof entry === "number")
-        return normalizeSpeedRate(entry);
-    if (!entry || typeof entry !== "object" || Array.isArray(entry))
-        return undefined;
-    const record = entry;
-    const rate = normalizeSpeedRate(record.rate);
-    if (rate === undefined)
-        return undefined;
-    const label = trimOptionalText(record.label);
-    const ariaLabel = trimOptionalText(record.ariaLabel);
-    return {
-        rate,
-        ...(label ? { label } : {}),
-        ...(ariaLabel ? { ariaLabel } : {}),
-    };
-};
-export const normalizeTTSSpeedOptionConfigs = (value) => {
-    if (!Array.isArray(value))
-        return [...DEFAULT_TTS_SPEED_OPTIONS];
-    if (value.length === 0)
-        return [];
-    const dedupedRates = new Set();
-    const normalized = [];
-    for (const entry of value) {
-        const option = normalizeTTSSpeedOptionConfig(entry);
-        if (option === undefined)
-            continue;
-        const rate = typeof option === "number" ? option : option.rate;
-        if (dedupedRates.has(rate))
-            continue;
-        dedupedRates.add(rate);
-        normalized.push(option);
-    }
-    return normalized.length ? normalized : [...DEFAULT_TTS_SPEED_OPTIONS];
-};
-/**
- * Resolves inline toolbar speed options from host config.
- * - Omitted/non-array: default speed buttons.
- * - Empty array: hide speed buttons.
- * - Arrays that sanitize to no valid values: default speed buttons.
- * - 1.0× is never shown as a discrete speed button.
- */
-export const normalizeTTSSpeedOptions = (value) => {
-    if (!Array.isArray(value))
-        return [...DEFAULT_TTS_SPEED_OPTIONS];
-    if (value.length === 0)
-        return [];
-    return normalizeTTSSpeedOptionConfigs(value).map((option) => typeof option === "number" ? option : option.rate);
-};
 export const normalizeTTSSpeedControlOptions = (value) => {
     const input = Array.isArray(value)
         ? value
@@ -117,11 +61,7 @@ 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" : formatSpeedLabel(rate);
         const label = typeof entry === "number"
             ? defaultLabel
             : trimOptionalText(record.label) || defaultLabel;
@@ -203,61 +143,42 @@ const applyRuntimeDefaults = (config) => {
         ...config,
         layoutMode: normalizeTTSLayoutMode(config.layoutMode),
     };
-    const backend = config.backend || "browser";
-    if (!isServerBackend(backend))
+    if (config.backend !== "server")
         return withLayoutDefaults;
     const withServerDefaults = {
         ...withLayoutDefaults,
         apiEndpoint: withDefault(withLayoutDefaults.apiEndpoint, "/api/tts"),
-        transportMode: withDefault(withLayoutDefaults.transportMode, "pie"),
+        transportMode: withDefault(withLayoutDefaults.transportMode, defaultTransportMode(config)),
         endpointValidationMode: withDefault(withLayoutDefaults.endpointValidationMode, "voices"),
-        validateEndpoint: withDefault(withLayoutDefaults.validateEndpoint, true),
         includeAuthOnAssetFetch: withDefault(withLayoutDefaults.includeAuthOnAssetFetch, false),
         rate: withDefault(withLayoutDefaults.rate, 1.0),
         language: withDefault(withLayoutDefaults.language, "en-US"),
     };
-    if (backend === "polly") {
+    if (config.serverProvider === "polly") {
         return {
             ...withServerDefaults,
-            defaultVoice: withDefault(withServerDefaults.defaultVoice, "Joanna"),
             engine: withDefault(withServerDefaults.engine, "neural"),
             format: withDefault(withServerDefaults.format, "mp3"),
             speechMarksMode: withDefault(withServerDefaults.speechMarksMode, "word+sentence"),
         };
     }
-    if (backend === "google") {
-        return {
-            ...withServerDefaults,
-            defaultVoice: withDefault(withServerDefaults.defaultVoice, "en-US-Wavenet-A"),
-        };
-    }
     return withServerDefaults;
 };
+/**
+ * The runtime settings of a `textToSpeech` provider entry: its top-level keys
+ * with defaults applied, an unknown `layoutMode` resolved to `left-aligned`.
+ * `enabled` and the runtime `provider` object belong to the tool registration
+ * and are dropped.
+ */
 export const resolveTTSRuntimeSettings = (config) => {
-    const configRecord = toRecord(config);
-    const settingsRecord = toRecord(configRecord.settings);
-    const { provider, ...merged } = { ...configRecord, ...settingsRecord };
-    // A runtime provider object in `provider` is for the tool registration; the
-    // runtime settings carry only a server provider id.
-    return applyRuntimeDefaults({
-        ...merged,
-        ...(typeof provider === "string" ? { provider } : {}),
-    });
+    const { enabled: _enabled, provider: _provider, ...settings } = toRecord(config);
+    return applyRuntimeDefaults(settings);
 };
 export const resolveTTSBackend = (config) => config.backend || "browser";
-export const resolveRuntimeProvider = (config, backend) => {
-    if (backend === "polly" || backend === "google")
-        return backend;
-    if (backend === "server") {
-        return config.serverProvider || config.provider;
-    }
-    return config.serverProvider || config.provider;
-};
-export const resolveTransportMode = (config, runtimeProvider) => config.transportMode || (runtimeProvider === "custom" ? "custom" : "pie");
 export const buildRuntimeTTSConfig = (config) => {
-    const backend = resolveTTSBackend(config);
-    const runtimeProvider = resolveRuntimeProvider(config, backend);
-    const transportMode = resolveTransportMode(config, runtimeProvider);
+    const runtimeProvider = resolveTTSBackend(config) === "server" ? config.serverProvider : undefined;
+    const polly = runtimeProvider === "polly";
+    const transportMode = config.transportMode || defaultTransportMode(config);
     const mathSpeech = normalizeSREMathSpeechOptions(config.mathSpeech);
     const runtimeConfig = {
         voice: config.defaultVoice,
@@ -266,16 +187,16 @@ export const buildRuntimeTTSConfig = (config) => {
         providerOptions: {
             ...toRecord(config.providerOptions),
             ...(config.language ? { locale: config.language } : {}),
-            ...(backend === "polly" && config.engine
+            ...(polly && config.engine
                 ? { engine: config.engine }
                 : {}),
-            ...(backend === "polly" && typeof config.sampleRate === "number"
+            ...(polly && typeof config.sampleRate === "number"
                 ? { sampleRate: config.sampleRate }
                 : {}),
-            ...(backend === "polly" && config.format
+            ...(polly && config.format
                 ? { format: config.format }
                 : {}),
-            ...(backend === "polly"
+            ...(polly
                 ? {
                     speechMarkTypes: config.speechMarksMode === "word+sentence"
                         ? ["word", "sentence"]
@@ -303,7 +224,6 @@ export const buildRuntimeTTSConfig = (config) => {
         assetOrigins: config.assetOrigins,
         credentials: config.credentials,
         headers: config.headers,
-        validateEndpoint: config.validateEndpoint,
         // Toolkit-level highlight setting carried through the config channel
         // (like apiEndpoint/transportMode); consumed by the highlight pipeline,
         // ignored by providers. Only forwarded when set so the pipeline default
@@ -314,13 +234,11 @@ export const buildRuntimeTTSConfig = (config) => {
     };
     return runtimeConfig;
 };
-export const resolveTTSLayoutMode = (config) => normalizeTTSLayoutMode(config.layoutMode);
+/** The toolbar layout hints for the layout mode of resolved settings. */
 export const resolveTTSHostToolbarLayout = (config) => {
-    const layoutMode = resolveTTSLayoutMode(config);
-    switch (layoutMode) {
+    switch (config.layoutMode) {
         case "reserved-row":
             return {
-                mount: "before-buttons",
                 controlsRow: {
                     reserveSpace: true,
                     expandWhenToolActive: false,
@@ -331,7 +249,6 @@ export const resolveTTSHostToolbarLayout = (config) => {
             };
         case "expanding-row":
             return {
-                mount: "before-buttons",
                 controlsRow: {
                     reserveSpace: false,
                     expandWhenToolActive: true,
@@ -342,7 +259,6 @@ export const resolveTTSHostToolbarLayout = (config) => {
             };
         case "floating-overlay":
             return {
-                mount: "before-buttons",
                 controlsRow: {
                     reserveSpace: false,
                     expandWhenToolActive: false,
@@ -354,7 +270,6 @@ export const resolveTTSHostToolbarLayout = (config) => {
         case "left-aligned":
         default:
             return {
-                mount: "before-buttons",
                 controlsRow: {
                     reserveSpace: false,
                     expandWhenToolActive: false,

package/dist/tools/content-capability-resolution.d.ts

@@ -3,7 +3,7 @@
  * profile.
  *
  * Two independent halves, and a capability is in play only when both answer yes:
- * policy granted one of its support ids, and its own `requiresAuthoredContent`
+ * policy granted its support id, and its own `requiresAuthoredContent`
  * found the resource in this entity's catalogs. Neither implies the other — a
  * learner with an accommodation still sees nothing on an item carrying no
  * resource, and an item carrying one shows nothing to a learner without the
@@ -30,13 +30,11 @@
  */
 import type { ToolRegistration } from "../services/ToolRegistry.js";
 import type { CatalogOwnerSnapshot } from "../services/AccessibilityCatalogResolver.js";
-/** What policy answered about one feature id. */
+/** What policy answered about one capability's support id. */
 export type ContentCapabilityPolicy = {
     outcome: "granted";
-    /** The support id that was granted — a capability may declare several. */
-    featureId: string;
     /** Feature parameters carried by the decision, if any. */
-    parameters?: unknown;
+    parameters?: Record<string, unknown>;
 }
 /**
  * No source granted it and none denied it. A capability declaring
@@ -61,13 +59,13 @@ export type ContentCapabilityPhase = "policy" | "content";
 export interface ResolvedContentCapability {
     registration: ToolRegistration;
     /**
-     * The granted support id, or `""` when the capability resolved without a
-     * grant. Passed through to the render context unchanged, so a capability that
+     * Whether policy granted the capability; `false` when it resolved from content
+     * alone. Passed through to the render context unchanged, so a capability that
      * serves both an authored-presentation case and an accommodation can still
      * tell them apart at render time.
      */
-    featureId: string;
-    parameters?: unknown;
+    granted: boolean;
+    parameters?: Record<string, unknown>;
     /** Whatever the capability's own `resolve` returned; never inspected here. */
     content: unknown;
 }
@@ -81,7 +79,7 @@ export interface ResolveContentCapabilitiesArgs {
     /** The entity's cards, or `null` when no resolver is available. */
     catalogs: CatalogOwnerSnapshot | null;
     /**
-     * Policy's answer about one feature id, in three states.
+     * Policy's answer about one support id, which is a tool id, in three states.
      *
      * Granting requires a documented need, so an unconfigured feature is
      * `"silent"`, never granted. What the third state buys is the distinction
@@ -89,7 +87,7 @@ export interface ResolveContentCapabilitiesArgs {
      * something, and a capability allowed to answer from content alone must not
      * treat that as nobody having spoken.
      */
-    policyFor: (featureId: string) => ContentCapabilityPolicy;
+    policyFor: (supportId: string) => ContentCapabilityPolicy;
     /**
      * Report a capability that threw. It is dropped either way; this is how a
      * caller surfaces it as its own recoverable warning rather than letting one

package/dist/tools/content-capability-resolution.js

@@ -3,7 +3,7 @@
  * profile.
  *
  * Two independent halves, and a capability is in play only when both answer yes:
- * policy granted one of its support ids, and its own `requiresAuthoredContent`
+ * policy granted its support id, and its own `requiresAuthoredContent`
  * found the resource in this entity's catalogs. Neither implies the other — a
  * learner with an accommodation still sees nothing on an item carrying no
  * resource, and an item carrying one shows nothing to a learner without the
@@ -28,51 +28,15 @@
  * a capability interprets its own cards, and the resolution owns only the
  * two-halves rule and its one documented exception.
  */
-/** The support ids a capability answers to, defaulting to its own id. */
-const supportIdsOf = (registration) => registration.pnpSupportIds?.length
-    ? registration.pnpSupportIds
-    : [registration.toolId];
-/**
- * Everything policy has to say about one capability: a grant, an off switch, or
- * nothing.
- *
- * Denial is checked ahead of a grant on each id rather than after the scan,
- * because the two can only disagree when a host blocked one of a capability's ids
- * while a profile granted another, and there the off switch is the later, more
- * specific statement about this delivery.
- *
- * A host gate names *capabilities*, so the tool id is probed too when it is not
- * already a declared support id — otherwise a capability whose id differs from
- * its support ids would slip a host block. That probe is gate-only: a grant on
- * the tool id is ignored, or blocking would double as a second way to switch a
- * capability on.
- */
-function policyForCapability(registration, args) {
-    const supportIds = supportIdsOf(registration);
-    for (const supportId of supportIds) {
-        const answer = args.policyFor(supportId);
-        if (answer.outcome === "denied")
-            return { grant: null, denied: true };
-        if (answer.outcome === "granted")
-            return { grant: answer, denied: false };
-    }
-    if (supportIds.includes(registration.toolId)) {
-        return { grant: null, denied: false };
-    }
-    return {
-        grant: null,
-        denied: args.policyFor(registration.toolId).outcome === "denied",
-    };
-}
 function resolveOne(registration, args) {
     let grant = null;
     try {
-        const answer = policyForCapability(registration, args);
-        // Nothing reopens a host denial — not a grant it outranked, and not the
-        // content exception below.
-        if (answer.denied)
+        const answer = args.policyFor(registration.toolId);
+        // Nothing reopens a host denial, not even the content exception below.
+        if (answer.outcome === "denied")
             return null;
-        grant = answer.grant;
+        if (answer.outcome === "granted")
+            grant = answer;
     }
     catch (error) {
         args.onError?.(registration, "policy", error);
@@ -92,13 +56,12 @@ function resolveOne(registration, args) {
             return null;
         return {
             registration,
-            featureId: grant.featureId,
+            granted: true,
             parameters: grant.parameters,
             content: null,
         };
     }
     const context = {
-        featureId: grant?.featureId ?? "",
         parameters: grant?.parameters,
         catalogs: args.catalogs,
         granted: Boolean(grant),
@@ -117,7 +80,7 @@ function resolveOne(registration, args) {
         return null;
     return {
         registration,
-        featureId: context.featureId,
+        granted: context.granted,
         parameters: context.parameters,
         content,
     };

package/dist/tools/registration.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Tool registration — the stable entry for tool authors: writing and rendering a
+ * `ToolRegistration`, and the runtime contract a tool element is written against.
+ *
+ * A capability package writes a registration with it: the registration contract,
+ * the context predicates a tool answers `isVisibleInContext` with, scoped ids,
+ * element creation, the toolbar button and overlay helpers, the provider contract
+ * a descriptor creates, and the TTS provider with its config resolution. A
+ * renderer puts registrations on screen with it: `createToolSurfaceHost` mounts
+ * and reconciles surfaces, and `resolveContentCapabilities` asks the
+ * grant-and-content question without a coordinator. A tool element connects to
+ * the runtime with it: the runtime, shell and region-scope contexts, the services
+ * they carry, coordinator registration, the reading scope of the content it reads
+ * or annotates, and read-aloud coordination.
+ *
+ * The composition layer (`@pie-players/pie-default-tool-loaders`), the packaged
+ * tools and the section player's tool panels are written against it, so a host's
+ * own tool uses the mechanism ours use. Its values are complete, so a tool
+ * package never imports the root entry, which carries what hosts and players
+ * import. A name the root also carries appears here only where a package imports
+ * it from here.
+ */
+export type { HostedToolContext, HostedToolSize, ToolContentDependencyContext, ToolModuleLoader, ToolProviderDescriptor, ToolRegistration, ToolRenderElement, ToolSurfaceRenderContext, ToolSurfaceRenderResult, ToolSurfaceServices, ToolToolbarButtonDefinition, ToolToolbarRenderResult, ToolbarContext, } from "../services/ToolRegistry.js";
+export { ToolRegistry } from "../services/ToolRegistry.js";
+export { resolveToolRegistrationName } from "../services/ToolRegistry.js";
+export type { ToolFailurePhase } from "../services/tool-failure.js";
+export { reportToolFailure } from "../services/tool-failure.js";
+export type { CatalogOwnerSnapshot } from "../services/AccessibilityCatalogResolver.js";
+export type { ToolSelectionAction, ToolSelectionContext, } from "../services/selection-action.js";
+export { resolveFallbackToolIcon } from "../services/tool-icons.js";
+export type { ContentCapabilityPhase, ContentCapabilityPolicy, ResolveContentCapabilitiesArgs, ResolvedContentCapability, } from "./content-capability-resolution.js";
+export { resolveContentCapabilities } from "./content-capability-resolution.js";
+export type { ToolSurfaceHost, ToolSurfaceHostInput, ToolSurfaceHostOptions, ToolSurfaceHostSnapshot, ToolSurfaceScope, } from "./tool-surface-host.js";
+export { createToolSurfaceHost } from "./tool-surface-host.js";
+export type { ToolContext } from "../services/tool-context.js";
+export { hasChoiceInteraction, hasMathContent, hasReadableText, hasSpokenContent, hasScienceContent, } from "../services/tool-context.js";
+export type { ParsedToolInstanceId } from "../services/tool-instance-id.js";
+export { createScopedToolId, parseScopedToolId, } from "../services/tool-instance-id.js";
+export type { ToolComponentFactory, ToolComponentFactoryMap, ToolComponentOverrides, ToolTagMap, } from "./tool-tag-map.js";
+export { createToolElement, resolveToolTag } from "./tool-tag-map.js";
+export { applyOverlaySurface, createScopedVisibilityBinding, syncButtonAndOverlayVisibility, TOOL_ACTIVE_CHANGE_EVENT, } from "./registrations/toolbar-registration-helpers.js";
+export type { HighlightCoordinatorApi, ToolCoordinatorApi, ToolkitCoordinatorApi, TtsServiceApi, } from "../services/interfaces.js";
+export type { AssessmentToolkitRegionScopeContext, AssessmentToolkitRuntimeContext, AssessmentToolkitShellContext, } from "../context/assessment-toolkit-context.js";
+export { connectToolRegionScopeContext, connectToolRuntimeContext, connectToolShellContext, createToolCoordinatorRegistration, type ToolCoordinatorRegistration, } from "../runtime/tool-host-contract.js";
+export { ZIndexLayer } from "../services/ToolCoordinator.js";
+export { HighlightColor, HighlightCoordinator, } from "../services/HighlightCoordinator.js";
+export type { CatalogLookupContext } from "../services/AccessibilityCatalogResolver.js";
+export { catalogContextForShell, catalogContextHolding, type CatalogRuntimeScope, } from "../runtime/catalog-context.js";
+export { findShellScopeHost, resolveContentRegion, } from "../runtime/content-region.js";
+export { composedClosest, composedContains, flatTextContent, isShadowRootNode, retargetToTree, } from "../services/tts/flat-tree.js";
+export type { ToolPlacementLevel } from "../services/tools-config-normalizer.js";
+export type { CalculatorToolProviderConfig, TextToSpeechToolProviderConfig, ToolProviderConfig, } from "../services/tools-config-normalizer.js";
+export type { ToolProviderApi } from "../services/tool-providers/ToolProviderApi.js";
+export { TTSToolProvider } from "../services/tool-providers/index.js";
+export type { NormalizedTTSSpeedOption, TTSLayoutMode, TTSSpeedOption, } from "../services/tts-runtime-config.js";
+export { buildRuntimeTTSConfig, formatTTSSpeedOptionsAsText, normalizeTTSSpeedControlOptions, parseTTSSpeedOptionsFromText, resolveTTSHostToolbarLayout, resolveTTSRuntimeSettings, } from "../services/tts-runtime-config.js";
+export { bindTtsAudioHandoff, pauseTtsForMediaAudio, } from "../services/audio-handoff.js";
+export { isTTSStartFailure } from "../services/tts/start-failure.js";
+export { browserVoiceMatchesLanguage, findBrowserVoice, waitForBrowserVoices, } from "../services/tts/browser-provider.js";

package/dist/tools/registration.js

@@ -0,0 +1,55 @@
+/**
+ * Tool registration — the stable entry for tool authors: writing and rendering a
+ * `ToolRegistration`, and the runtime contract a tool element is written against.
+ *
+ * A capability package writes a registration with it: the registration contract,
+ * the context predicates a tool answers `isVisibleInContext` with, scoped ids,
+ * element creation, the toolbar button and overlay helpers, the provider contract
+ * a descriptor creates, and the TTS provider with its config resolution. A
+ * renderer puts registrations on screen with it: `createToolSurfaceHost` mounts
+ * and reconciles surfaces, and `resolveContentCapabilities` asks the
+ * grant-and-content question without a coordinator. A tool element connects to
+ * the runtime with it: the runtime, shell and region-scope contexts, the services
+ * they carry, coordinator registration, the reading scope of the content it reads
+ * or annotates, and read-aloud coordination.
+ *
+ * The composition layer (`@pie-players/pie-default-tool-loaders`), the packaged
+ * tools and the section player's tool panels are written against it, so a host's
+ * own tool uses the mechanism ours use. Its values are complete, so a tool
+ * package never imports the root entry, which carries what hosts and players
+ * import. A name the root also carries appears here only where a package imports
+ * it from here.
+ */
+export { ToolRegistry } from "../services/ToolRegistry.js";
+// A registration's own display name in the interface locale. A tool window's
+// title is the registration's name, so the shell needs the same `nameKey`-then-
+// `name` precedence the toolbar uses rather than the raw English field.
+export { resolveToolRegistrationName } from "../services/ToolRegistry.js";
+export { reportToolFailure } from "../services/tool-failure.js";
+// So a gateway button and the toolbar button for the same tool draw one icon.
+export { resolveFallbackToolIcon } from "../services/tool-icons.js";
+export { resolveContentCapabilities } from "./content-capability-resolution.js";
+export { createToolSurfaceHost } from "./tool-surface-host.js";
+export { hasChoiceInteraction, hasMathContent, hasReadableText, hasSpokenContent, hasScienceContent, } from "../services/tool-context.js";
+export { createScopedToolId, parseScopedToolId, } from "../services/tool-instance-id.js";
+export { createToolElement, resolveToolTag } from "./tool-tag-map.js";
+// Toolbar button/overlay wiring shared by every toolbar-toggle registration,
+// and the event a tool element announces its own active state with.
+export { applyOverlaySurface, createScopedVisibilityBinding, syncButtonAndOverlayVisibility, TOOL_ACTIVE_CHANGE_EVENT, } from "./registrations/toolbar-registration-helpers.js";
+export { connectToolRegionScopeContext, connectToolRuntimeContext, connectToolShellContext, createToolCoordinatorRegistration, } from "../runtime/tool-host-contract.js";
+export { ZIndexLayer } from "../services/ToolCoordinator.js";
+export { HighlightColor, HighlightCoordinator, } from "../services/HighlightCoordinator.js";
+export { catalogContextForShell, catalogContextHolding, } from "../runtime/catalog-context.js";
+export { findShellScopeHost, resolveContentRegion, } from "../runtime/content-region.js";
+export { composedClosest, composedContains, flatTextContent, isShadowRootNode, retargetToTree, } from "../services/tts/flat-tree.js";
+// The TTS provider stays here because it is written against the `pie-tts`
+// contract package, which the toolkit's own `TTSService` also depends on.
+export { TTSToolProvider } from "../services/tool-providers/index.js";
+export { buildRuntimeTTSConfig, formatTTSSpeedOptionsAsText, normalizeTTSSpeedControlOptions, parseTTSSpeedOptionsFromText, resolveTTSHostToolbarLayout, resolveTTSRuntimeSettings, } from "../services/tts-runtime-config.js";
+// Read-aloud coordination for a tool that plays or controls speech: pausing
+// speech while a media element plays, recognising a start failure the TTS
+// service reports, and choosing a browser voice for a language once the browser
+// has published its voices.
+export { bindTtsAudioHandoff, pauseTtsForMediaAudio, } from "../services/audio-handoff.js";
+export { isTTSStartFailure } from "../services/tts/start-failure.js";
+export { browserVoiceMatchesLanguage, findBrowserVoice, waitForBrowserVoices, } from "../services/tts/browser-provider.js";