@pie-players/pie-assessment-toolkit 0.3.67 → 0.3.69

package/dist/services/ToolRegistry.js

@@ -4,7 +4,37 @@
  * Central registry for all assessment tools. Manages tool metadata, visibility logic,
  * and button/instance creation. Supports dynamic registration and override by integrators.
  */
+import { dynamicMessageKey } from "@pie-players/pie-players-shared/i18n/provider";
 import { normalizeToolAlias } from "./tools-config-normalizer.js";
+/**
+ * A registration's display name in the interface locale.
+ *
+ * Precedence: the resolved `nameKey`, then `name`. A key that does not resolve
+ * falls back to `name` rather than rendering the key, so a catalog gap degrades
+ * to English instead of to `tools.something.name` on a toolbar button.
+ *
+ * Both display resolvers live here so the toolbars, the settings panels and the
+ * PNP debugger cannot each invent their own precedence.
+ */
+export function resolveToolRegistrationName(registration, i18n) {
+    return resolveKeyedString(registration.name, registration.nameKey, i18n);
+}
+/** A registration's description in the interface locale. See the name resolver. */
+export function resolveToolRegistrationDescription(registration, i18n) {
+    return resolveKeyedString(registration.description, registration.descriptionKey, i18n);
+}
+function resolveKeyedString(source, key, i18n) {
+    if (!key || !i18n)
+        return source;
+    // A registration may be host-authored against a host catalog, so the key is
+    // not drawn from PIE's `MessageKey` union and has to be asserted.
+    const messageKey = dynamicMessageKey(key);
+    if (i18n.hasKey)
+        return i18n.hasKey(messageKey) ? i18n.t(messageKey) : source;
+    // A provider without `hasKey` still signals a miss by returning the key.
+    const resolved = i18n.t(messageKey);
+    return resolved === key ? source : resolved;
+}
 const VALID_TOOL_LEVELS = [
     "assessment",
     "section",
@@ -134,6 +164,10 @@ function assertToolRegistrationShape(registration) {
         typeof registration.isVisibleInContext !== "function") {
         throw new Error(`Invalid tool registration "${registration.toolId}": "isVisibleInContext" must be a function when present.`);
     }
+    if (registration.isApplicableToContent !== undefined &&
+        typeof registration.isApplicableToContent !== "function") {
+        throw new Error(`Invalid tool registration "${registration.toolId}": "isApplicableToContent" must be a function when present.`);
+    }
     if (registration.requiresAuthoredContent !== undefined) {
         if (typeof registration.requiresAuthoredContent !== "object" ||
             registration.requiresAuthoredContent === null ||
@@ -412,6 +446,36 @@ export class ToolRegistry {
         }
         return visible;
     }
+    /**
+     * Whether a tool can act on any of the contexts it would be placed against.
+     * Unlike the relevance pass this is a veto: a `false` here removes the tool
+     * from a toolbar even when a grant protects it, so a tool answers `false`
+     * only where its controls provably do nothing.
+     *
+     * A tool that declares no applicability gate is applicable. So is one
+     * evaluated against no contexts — content that has not resolved yet cannot
+     * establish that a tool is useless.
+     *
+     * @param toolId - Tool to ask
+     * @param contexts - Every context the tool could act on at this placement
+     */
+    isApplicableToAnyContext(toolId, contexts) {
+        const tool = this.get(toolId);
+        if (!tool?.isApplicableToContent)
+            return true;
+        if (contexts.length === 0)
+            return true;
+        return contexts.some((context) => {
+            try {
+                return tool.isApplicableToContent?.(context) ?? true;
+            }
+            catch (error) {
+                console.error(`Error evaluating applicability for tool '${toolId}':`, error);
+                // A gate that throws has not established that the tool is useless.
+                return true;
+            }
+        });
+    }
     /**
      * Get tool metadata for building UIs
      * Useful for building PNP configuration interfaces

package/dist/services/ToolkitCoordinator.d.ts

@@ -24,13 +24,14 @@ import { FrameworkErrorBus, type FrameworkErrorListener } from "./framework-erro
 import { HighlightCoordinator } from "./HighlightCoordinator.js";
 import { ToolCoordinator } from "./ToolCoordinator.js";
 import { TTSService } from "./TTSService.js";
-import { type TTSSpeedOption, type TTSLayoutMode } from "./tts-runtime-config.js";
+import { type TTSRuntimeSettings } from "./tts-runtime-config.js";
 import type { SREMathSpeechOptions } from "./tts/math-speech.js";
 import { ToolProviderRegistry } from "./tool-providers/index.js";
 import type { ToolProviderApi } from "./tool-providers/ToolProviderApi.js";
 import type { TTSToolProviderConfig } from "./tool-providers/index.js";
 import { ToolRegistry } from "./ToolRegistry.js";
 import type { ResolvedToolContext, ToolContextResolver, ToolContextResolverContext, ToolContextResolverMap } from "./ToolRegistry.js";
+import type { ToolOpenRequest, ToolRequestTarget } from "./tool-request.js";
 import { type FeaturePolicyDecision, type PnpEnforcementMode, type PolicySource, type ResolvedEngineInputs, type ToolPolicyChangeListener, type ToolPolicyDecision, type ToolPolicyDecisionRequest } from "../policy/engine.js";
 import type { SectionControllerContext, SectionControllerEvent, SectionControllerEventType, SectionControllerFactoryDefaults, SectionControllerHandle, SectionControllerKey, SectionSessionPersistenceStrategy, SectionPersistenceFactoryDefaults } from "./section-controller-types.js";
 export type { SectionControllerContext, SectionControllerEvent, SectionControllerEventType, SectionControllerFactoryDefaults, SectionControllerHandle, SectionControllerKey, SectionControllerLoadedRenderable, SectionSessionPersistenceConfig, SectionSessionPersistenceStrategy, SectionControllerRuntimeState, SectionControllerSessionState, SectionPersistenceFactoryDefaults, } from "./section-controller-types.js";
@@ -45,45 +46,25 @@ export interface ToolConfig {
     [key: string]: unknown;
 }
 /**
- * TTS tool configuration
+ * TTS configuration as a host writes it.
+ *
+ * The field set is `TTSRuntimeSettings`, which the runtime resolver owns: the two
+ * were declared separately and had already drifted in both directions, so a field
+ * the runtime honoured could not be named here. What this adds is the two things
+ * only a host-facing config has — a place to stash unrecognised keys, and a
+ * callback for fetching provider credentials, neither of which the resolved
+ * runtime settings carry.
+ *
+ * An intersection rather than an interface: `ToolConfig.provider` is `unknown`
+ * where the runtime settings narrow it to the three provider ids, and an interface
+ * cannot inherit a member from two parents that type it differently.
  */
-export interface TTSToolConfig extends ToolConfig {
-    backend?: "browser" | "polly" | "google" | "server";
-    provider?: "polly" | "google" | "custom";
-    serverProvider?: "polly" | "google" | "custom";
-    engine?: "standard" | "neural";
-    sampleRate?: number;
-    format?: "mp3" | "ogg" | "pcm";
-    speechMarksMode?: "word" | "word+sentence";
-    defaultVoice?: string;
-    rate?: number;
-    pitch?: number;
-    apiEndpoint?: string;
-    language?: string;
-    transportMode?: "pie" | "custom";
-    endpointMode?: "synthesizePath" | "rootPost";
-    endpointValidationMode?: "voices" | "endpoint" | "none";
-    includeAuthOnAssetFetch?: boolean;
-    validateEndpoint?: boolean;
-    cache?: boolean;
-    speedRate?: "slow" | "medium" | "fast";
-    lang_id?: string;
-    /**
-     * Optional inline TTS speed buttons.
-     * - Omitted/non-array: default speed buttons are shown.
-     * - Empty array: hide speed buttons.
-     * - Arrays that sanitize to no valid values: default speed buttons are shown.
-     * - Object entries can customize button text while preserving numeric rates.
-     */
-    speedOptions?: TTSSpeedOption[];
-    layoutMode?: TTSLayoutMode;
-    /** Speech Rule Engine options for generated MathML speech. */
-    mathSpeech?: SREMathSpeechOptions;
+export type TTSToolConfig = ToolConfig & TTSRuntimeSettings & {
     settings?: Record<string, unknown> & {
         mathSpeech?: SREMathSpeechOptions;
     };
     authFetcher?: () => Promise<Partial<TTSToolProviderConfig>>;
-}
+};
 /**
  * Answer eliminator tool configuration
  */
@@ -205,8 +186,8 @@ export interface SectionEventSubscriptionArgs {
     eventTypes?: readonly SectionControllerEventType[];
     itemIds?: readonly string[];
 }
-export type SectionItemEventType = Exclude<SectionControllerEventType, "section-navigation-change" | "section-session-applied" | "section-loading-complete" | "section-items-complete-changed" | "section-error">;
-export type SectionScopedEventType = Extract<SectionControllerEventType, "section-navigation-change" | "section-session-applied" | "section-loading-complete" | "section-items-complete-changed" | "section-error">;
+export type SectionItemEventType = Exclude<SectionControllerEventType, "section-navigation-change" | "section-session-applied" | "section-loading-complete" | "section-items-complete-changed" | "section-error" | "timed-media-cue-changed" | "timed-media-policy-degraded" | "timed-media-invalid">;
+export type SectionScopedEventType = Extract<SectionControllerEventType, "section-navigation-change" | "section-session-applied" | "section-loading-complete" | "section-items-complete-changed" | "section-error" | "timed-media-cue-changed" | "timed-media-policy-degraded" | "timed-media-invalid">;
 export type SectionItemEvent = Extract<SectionControllerEvent, {
     type: SectionItemEventType;
 }>;
@@ -339,6 +320,7 @@ export declare class ToolkitCoordinator {
     private readonly toolRegistry;
     private readonly toolContextResolvers;
     private readonly toolContextResolverChangeListeners;
+    private readonly toolRequests;
     private readonly sectionControllers;
     private readonly sectionControllerKeys;
     private readonly sectionControllerInitPromises;
@@ -778,6 +760,26 @@ export declare class ToolkitCoordinator {
     hasToolContextResolver(toolId: string): boolean;
     resolveToolContext(context: ToolContextResolverContext): ResolvedToolContext | null;
     onToolContextResolverChange(listener: () => void): () => void;
+    /**
+     * Claim requests for one placement level. Called by a toolbar on mount.
+     */
+    registerToolRequestTarget(target: ToolRequestTarget): () => void;
+    /**
+     * Ask the toolbar hosting a tool to open it, handing it `params`.
+     *
+     * Returns whether a toolbar claimed the request. A surface offering this as an
+     * affordance should gate on {@link canRequestTool} first rather than acting on
+     * the return value, so the learner never sees a control that does nothing.
+     */
+    requestTool(request: ToolOpenRequest): boolean;
+    /**
+     * Answers `false` for a tool this deployment does not carry rather than
+     * throwing as {@link requestTool} does. A composer asks this while rendering a
+     * surface, and a host that swapped the registry for one without the tool would
+     * otherwise lose the whole surface to an exception over an absent action.
+     */
+    canRequestTool(toolId: string, level?: ToolOpenRequest["level"]): boolean;
+    onToolRequestTargetsChange(listener: () => void): () => void;
     /**
      * Compute the effective PNP/profile enforcement mode given the explicit
      * host override and the auto-mode helper.

package/dist/services/ToolkitCoordinator.js

@@ -26,6 +26,7 @@ import { BrowserTTSProvider } from "./tts/browser-provider.js";
 import { buildRuntimeTTSConfig, resolveTTSBackend, resolveTTSRuntimeSettings, } from "./tts-runtime-config.js";
 import { ToolProviderRegistry } from "./tool-providers/index.js";
 import { ToolRegistry } from "./ToolRegistry.js";
+import { ToolRequestRegistry } from "./tool-request.js";
 import { ToolPolicyEngine, } from "../policy/engine.js";
 import { resolveDefaultPnpEnforcement } from "../policy/internal.js";
 const isPlainRecord = (value) => !!value && typeof value === "object" && !Array.isArray(value);
@@ -59,6 +60,9 @@ const SECTION_SCOPED_EVENT_TYPES = [
     "section-loading-complete",
     "section-items-complete-changed",
     "section-error",
+    "timed-media-cue-changed",
+    "timed-media-policy-degraded",
+    "timed-media-invalid",
 ];
 /**
  * ToolkitCoordinator - Orchestrates all assessment toolkit services
@@ -113,6 +117,7 @@ export class ToolkitCoordinator {
     toolRegistry;
     toolContextResolvers = new Map();
     toolContextResolverChangeListeners = new Set();
+    toolRequests = new ToolRequestRegistry();
     sectionControllers = new Map();
     sectionControllerKeys = new Map();
     sectionControllerInitPromises = new Map();
@@ -1741,6 +1746,41 @@ export class ToolkitCoordinator {
             this.toolContextResolverChangeListeners.delete(listener);
         };
     }
+    /**
+     * Claim requests for one placement level. Called by a toolbar on mount.
+     */
+    registerToolRequestTarget(target) {
+        return this.toolRequests.registerTarget(target);
+    }
+    /**
+     * Ask the toolbar hosting a tool to open it, handing it `params`.
+     *
+     * Returns whether a toolbar claimed the request. A surface offering this as an
+     * affordance should gate on {@link canRequestTool} first rather than acting on
+     * the return value, so the learner never sees a control that does nothing.
+     */
+    requestTool(request) {
+        this.assertCanonicalToolId(request.toolId);
+        return this.toolRequests.request(request);
+    }
+    /**
+     * Answers `false` for a tool this deployment does not carry rather than
+     * throwing as {@link requestTool} does. A composer asks this while rendering a
+     * surface, and a host that swapped the registry for one without the tool would
+     * otherwise lose the whole surface to an exception over an absent action.
+     */
+    canRequestTool(toolId, level) {
+        try {
+            this.assertCanonicalToolId(toolId);
+        }
+        catch {
+            return false;
+        }
+        return this.toolRequests.canRequest(toolId, level);
+    }
+    onToolRequestTargetsChange(listener) {
+        return this.toolRequests.onTargetsChange(listener);
+    }
     /**
      * Compute the effective PNP/profile enforcement mode given the explicit
      * host override and the auto-mode helper.

package/dist/services/audio-handoff.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Audio handoff between read-aloud and a media surface.
+ *
+ * One learner, one pair of ears: read-aloud and media audio must never run at
+ * once, and the action the learner just took wins. Every media surface in the
+ * toolkit's graph needs both halves of that rule — pause yourself when speech
+ * starts, pause speech when you start — and there are already two such surfaces
+ * (the signing region, a timed-media stimulus reached through its port) with
+ * nothing in common but this. Shared so the rule has one statement: which states
+ * count as speaking is the part that would drift.
+ *
+ * Neither half resumes what it silenced. The learner presses play.
+ */
+import type { TtsServiceApi } from "./interfaces.js";
+/** Only what a handoff needs, so a host passing a partial service still works. */
+type TtsHandoffSubscriber = Pick<TtsServiceApi, "onStateChange" | "offStateChange">;
+type TtsHandoffPlayback = Pick<TtsServiceApi, "isPlaying" | "pause">;
+/**
+ * Silence a media surface whenever read-aloud starts speaking.
+ *
+ * `LOADING` as well as `PLAYING`, so the pause lands before the first word rather
+ * than a provider round-trip after it. A `LOADING` that then fails leaves media
+ * paused, which costs the learner one press of play.
+ *
+ * Returns the teardown, including where there was nothing to bind.
+ */
+export declare function bindTtsAudioHandoff(args: {
+    ttsService: Partial<TtsHandoffSubscriber> | null | undefined;
+    /** Unique per surface: the service keys its listener sets by this. */
+    listenerId: string;
+    silence: () => void;
+}): () => void;
+/**
+ * The other half: media audio has started, so read-aloud yields.
+ *
+ * Paused rather than stopped, so the learner keeps their place in the passage.
+ */
+export declare function pauseTtsForMediaAudio(ttsService: Partial<TtsHandoffPlayback> | null | undefined): void;
+export {};

package/dist/services/audio-handoff.js

@@ -0,0 +1,58 @@
+/**
+ * Audio handoff between read-aloud and a media surface.
+ *
+ * One learner, one pair of ears: read-aloud and media audio must never run at
+ * once, and the action the learner just took wins. Every media surface in the
+ * toolkit's graph needs both halves of that rule — pause yourself when speech
+ * starts, pause speech when you start — and there are already two such surfaces
+ * (the signing region, a timed-media stimulus reached through its port) with
+ * nothing in common but this. Shared so the rule has one statement: which states
+ * count as speaking is the part that would drift.
+ *
+ * Neither half resumes what it silenced. The learner presses play.
+ */
+import { PlaybackState } from "./TTSService.js";
+const NOOP = () => { };
+/**
+ * Silence a media surface whenever read-aloud starts speaking.
+ *
+ * `LOADING` as well as `PLAYING`, so the pause lands before the first word rather
+ * than a provider round-trip after it. A `LOADING` that then fails leaves media
+ * paused, which costs the learner one press of play.
+ *
+ * Returns the teardown, including where there was nothing to bind.
+ */
+export function bindTtsAudioHandoff(args) {
+    const { ttsService, listenerId, silence } = args;
+    if (typeof ttsService?.onStateChange !== "function")
+        return NOOP;
+    const onTtsState = (state) => {
+        if (state !== PlaybackState.PLAYING && state !== PlaybackState.LOADING) {
+            return;
+        }
+        silence();
+    };
+    ttsService.onStateChange(listenerId, onTtsState);
+    return () => {
+        try {
+            ttsService.offStateChange?.(listenerId, onTtsState);
+        }
+        catch {
+            // A torn-down service is not a failure to detach from.
+        }
+    };
+}
+/**
+ * The other half: media audio has started, so read-aloud yields.
+ *
+ * Paused rather than stopped, so the learner keeps their place in the passage.
+ */
+export function pauseTtsForMediaAudio(ttsService) {
+    try {
+        if (ttsService?.isPlaying?.())
+            ttsService.pause?.();
+    }
+    catch {
+        // A torn-down or uninitialized TTS service must not break playback.
+    }
+}

package/dist/services/catalog-media.d.ts

@@ -12,14 +12,45 @@
  * Part of PIE Assessment Toolkit.
  */
 import type { MediaFragmentRange, MediaSource } from "@pie-players/pie-players-shared/types";
+/**
+ * The only `MediaAssetRef.version` this build renders.
+ *
+ * `media-asset-contract.md` requires unknown-version rejection for runtime
+ * rendering: bumping to `2` obliges every consumer to accept both for as long as
+ * any producer emits `1`, so a card claiming a version this build does not
+ * implement must not be rendered on a guess at which fields still mean what they
+ * did.
+ */
+export declare const SUPPORTED_MEDIA_ASSET_VERSION = 1;
+/**
+ * Whether a media reference claims a version this build cannot render.
+ *
+ * An absent `version` is accepted rather than rejected — the same posture the
+ * rest of this module takes toward absent fields, and the one `media.kind` and
+ * `matchesRequestedSignLanguage` already take: only a positive claim of
+ * something else is refused. Producers predate the field, and treating its
+ * absence as a rejection would drop cards that are otherwise wholly valid.
+ */
+export declare function isUnsupportedMediaAssetVersion(version: unknown): boolean;
 export declare function isSafeMediaSrc(raw: unknown): raw is string;
 export declare function normalizeMediaSources(raw: unknown): MediaSource[];
 export declare function normalizeMediaFragment(raw: unknown): MediaFragmentRange | undefined;
 export declare function trimmedOrUndefined(value: unknown): string | undefined;
 /**
- * Apply a fragment range to a source URL as a Media Fragments URI, so one
- * recording can serve several content nodes. Browsers honour the start offset;
- * the end offset is enforced by the caller, because support for the end bound is
- * inconsistent.
+ * Hold a media element to one fragment's range, and return the disposer.
+ *
+ * The `#t=` URI `applyMediaFragment` writes is a hint browsers honour at neither
+ * bound reliably, so every consumer that means "play only this slice" enforces it
+ * here instead of reimplementing the pair. Both shipped consumers do —
+ * `SignLanguageMediaRegion` pausing at the end, `TTSService.playRecordedAudio`
+ * ending the clip so the chunk sequence advances — which is why the end action is
+ * the caller's and only the arithmetic is shared.
+ *
+ * The start seek is forward only: a browser that did honour the URI has already
+ * positioned past the start, and seeking back would replay audio the learner has
+ * heard. `onReachedEnd` may fire more than once and must tolerate it; polling
+ * stops while the element is paused, so an element left sitting past its end bound
+ * goes quiet rather than being told repeatedly.
  */
+export declare function enforceMediaFragment(element: HTMLMediaElement, fragment: MediaFragmentRange | undefined, onReachedEnd: () => void): () => void;
 export declare function applyMediaFragment(src: string, fragment?: MediaFragmentRange): string;

package/dist/services/catalog-media.js

@@ -20,6 +20,28 @@
  */
 const DISALLOWED_SRC_SCHEME = /^[a-z][a-z0-9+.-]*:/i;
 const ALLOWED_SRC_SCHEMES = new Set(["http:", "https:", "data:", "blob:"]);
+/**
+ * The only `MediaAssetRef.version` this build renders.
+ *
+ * `media-asset-contract.md` requires unknown-version rejection for runtime
+ * rendering: bumping to `2` obliges every consumer to accept both for as long as
+ * any producer emits `1`, so a card claiming a version this build does not
+ * implement must not be rendered on a guess at which fields still mean what they
+ * did.
+ */
+export const SUPPORTED_MEDIA_ASSET_VERSION = 1;
+/**
+ * Whether a media reference claims a version this build cannot render.
+ *
+ * An absent `version` is accepted rather than rejected — the same posture the
+ * rest of this module takes toward absent fields, and the one `media.kind` and
+ * `matchesRequestedSignLanguage` already take: only a positive claim of
+ * something else is refused. Producers predate the field, and treating its
+ * absence as a rejection would drop cards that are otherwise wholly valid.
+ */
+export function isUnsupportedMediaAssetVersion(version) {
+    return version !== undefined && version !== SUPPORTED_MEDIA_ASSET_VERSION;
+}
 export function isSafeMediaSrc(raw) {
     if (typeof raw !== "string")
         return false;
@@ -85,10 +107,77 @@ export function trimmedOrUndefined(value) {
 }
 /**
  * Apply a fragment range to a source URL as a Media Fragments URI, so one
- * recording can serve several content nodes. Browsers honour the start offset;
- * the end offset is enforced by the caller, because support for the end bound is
- * inconsistent.
+ * recording can serve several content nodes.
+ *
+ * The URI is a hint only: browsers honour both bounds inconsistently, so the
+ * caller enforces the range itself — seek forward to the start once metadata is
+ * available, and stop at the end. `SignLanguageMediaRegion` and
+ * `TTSService.playRecordedAudio` are the two shipped consumers that do so.
+ */
+/**
+ * How often the end bound is re-checked while a slice is playing. `timeupdate`
+ * alone fires about four times a second, which is loose enough to leak a sliver
+ * of the next node's recording.
+ */
+const END_CHECK_INTERVAL_MS = 100;
+/** `HTMLMediaElement.HAVE_METADATA`, which not every DOM implementation exposes. */
+const HAVE_METADATA = 1;
+/**
+ * Hold a media element to one fragment's range, and return the disposer.
+ *
+ * The `#t=` URI `applyMediaFragment` writes is a hint browsers honour at neither
+ * bound reliably, so every consumer that means "play only this slice" enforces it
+ * here instead of reimplementing the pair. Both shipped consumers do —
+ * `SignLanguageMediaRegion` pausing at the end, `TTSService.playRecordedAudio`
+ * ending the clip so the chunk sequence advances — which is why the end action is
+ * the caller's and only the arithmetic is shared.
+ *
+ * The start seek is forward only: a browser that did honour the URI has already
+ * positioned past the start, and seeking back would replay audio the learner has
+ * heard. `onReachedEnd` may fire more than once and must tolerate it; polling
+ * stops while the element is paused, so an element left sitting past its end bound
+ * goes quiet rather than being told repeatedly.
  */
+export function enforceMediaFragment(element, fragment, onReachedEnd) {
+    if (!fragment)
+        return () => { };
+    const { startSeconds, endSeconds } = fragment;
+    let seekToStart;
+    if (startSeconds > 0) {
+        seekToStart = () => {
+            if (element.currentTime < startSeconds) {
+                element.currentTime = startSeconds;
+            }
+        };
+        // Seeking before metadata is available only sets the default start
+        // position, so wait for it unless it already landed.
+        if (element.readyState >= HAVE_METADATA)
+            seekToStart();
+        else
+            element.addEventListener("loadedmetadata", seekToStart);
+    }
+    let checkEnd;
+    let endPoll;
+    if (endSeconds !== undefined) {
+        checkEnd = () => {
+            if (element.currentTime >= endSeconds)
+                onReachedEnd();
+        };
+        element.addEventListener("timeupdate", checkEnd);
+        endPoll = setInterval(() => {
+            if (!element.paused)
+                checkEnd?.();
+        }, END_CHECK_INTERVAL_MS);
+    }
+    return () => {
+        if (seekToStart)
+            element.removeEventListener("loadedmetadata", seekToStart);
+        if (checkEnd)
+            element.removeEventListener("timeupdate", checkEnd);
+        if (endPoll !== undefined)
+            clearInterval(endPoll);
+    };
+}
 export function applyMediaFragment(src, fragment) {
     if (!fragment)
         return src;

package/dist/services/framework-error.d.ts

@@ -1,5 +1,19 @@
 import type { ToolConfigDiagnostic } from "./tool-config-validation.js";
-export type FrameworkErrorKind = "tool-config" | "runtime-init" | "runtime-dispose" | "coordinator-init" | "provider-init" | "provider-register" | "tts-init" | "tool-state-load" | "tool-state-save" | "section-controller-init" | "section-controller-dispose" | "tool-surface" | "unknown";
+export type FrameworkErrorKind = "tool-config" | "runtime-init" | "runtime-dispose" | "coordinator-init" | "provider-init" | "provider-register" | "tts-init" | "tool-state-load" | "tool-state-save" | "section-controller-init" | "section-controller-dispose" | "tool-surface"
+/**
+ * A timed-media section could not deliver a policy as authored: a media time
+ * source missing `canPause` / `canRestrictSeeking` (recoverable — cues still
+ * fire and state is still recorded, only enforcement is lost), or authored
+ * `timedMedia` that failed validation (not recoverable — the section delivers
+ * as an ordinary section instead).
+ */
+ | "timed-media"
+/**
+ * An interface-locale catalog failed to load. Recoverable by construction: every
+ * key still resolves through the English fallback chain, so the player renders
+ * — in the wrong language, which a host wants to know about.
+ */
+ | "i18n-locale-load" | "unknown";
 export type FrameworkErrorSeverity = "warning" | "error";
 export interface FrameworkErrorModel {
     kind: FrameworkErrorKind;

package/dist/services/interfaces.d.ts

@@ -25,6 +25,7 @@ import type { FeaturePolicyDecision, PolicySource, PnpEnforcementMode, ResolvedE
 import type { AssessmentEntity, AssessmentItemRef } from "@pie-players/pie-players-shared/types";
 import type { ITTSProvider, TTSProviderCapabilities } from "@pie-players/pie-tts";
 import type { ResolvedToolContext, ToolContextResolver, ToolContextResolverContext, ToolContextResolverMap } from "./ToolRegistry.js";
+import type { ToolOpenRequest, ToolRequestTarget } from "./tool-request.js";
 export type { I18nServiceApi };
 /**
  * Theme provider interface
@@ -702,4 +703,31 @@ export interface ToolkitCoordinatorApi {
      * Subscribe to resolver registration/removal changes.
      */
     onToolContextResolverChange(listener: () => void): () => void;
+    /**
+     * The tool-open request seam, optional as a group.
+     *
+     * `ToolkitCoordinator` implements all four. They are optional here because a host
+     * may supply a coordinator of its own that predates the seam, and a surface that
+     * pairs a selection action to a tool already has to check before offering a button
+     * it cannot service. Declaring them required would make such a coordinator
+     * structurally non-conformant while every call site guards anyway.
+     */
+    /** Claim tool-open requests for one placement level. Toolbars call this. */
+    registerToolRequestTarget?(target: ToolRequestTarget): () => void;
+    /**
+     * Ask the toolbar hosting a tool to open it with `params`, and report whether
+     * one claimed the request. Lets a selection gateway hand the learner's
+     * selection to a tool it neither mounts nor can name a scoped instance of.
+     */
+    requestTool?(request: ToolOpenRequest): boolean;
+    /**
+     * Whether a request for this tool would reach a toolbar. A surface asks before
+     * offering the affordance.
+     */
+    canRequestTool?(toolId: string, level?: ToolOpenRequest["level"]): boolean;
+    /**
+     * Subscribe to toolbar registration/removal, so a surface can re-evaluate the
+     * actions it offers.
+     */
+    onToolRequestTargetsChange?(listener: () => void): () => void;
 }

package/dist/services/pnp-standard-features.d.ts

@@ -167,7 +167,7 @@ export declare const QTI_STANDARD_ACCESS_FEATURES: {
 /**
  * Flat list of all standard access features for validation
  */
-export declare const ALL_STANDARD_ACCESS_FEATURES: ("transcript" | "braille" | "textToSpeech" | "calculator" | "strikethrough" | "answerEliminator" | "magnification" | "screenMagnifier" | "zoomable" | "highContrastDisplay" | "highContrastAudio" | "colorContrast" | "invertColors" | "displayTransformability" | "largePrint" | "fontEnlargement" | "resizeText" | "alternativeText" | "longDescription" | "describedMath" | "tactileGraphic" | "tactileObject" | "audioDescription" | "readAloud" | "humanVoice" | "syntheticVoice" | "speechRate" | "speechVolume" | "voicePitch" | "captions" | "closedCaptions" | "openCaptions" | "signLanguage" | "subtitles" | "audioControl" | "noBackgroundAudio" | "keyboardControl" | "mouseControl" | "touchControl" | "voiceControl" | "switchControl" | "eyeGazeControl" | "singleSwitchAccess" | "stickyKeys" | "keyboardShortcuts" | "timingControl" | "unlimitedTime" | "extendedTime" | "pauseControl" | "simplifiedLanguage" | "reducedComplexity" | "structuralNavigation" | "tableOfContents" | "reducedDistraction" | "noFlashing" | "pauseAnimation" | "annotations" | "bookmarking" | "highlighting" | "guidedNavigation" | "thesaurus" | "spellingAssistance" | "grammarAssistance" | "lineSpacing" | "wordSpacing" | "letterSpacing" | "fontFamily" | "readingMask" | "readingGuide" | "readingRuler" | "wordHighlighting" | "lineHighlighting" | "focusIndicator" | "printableResource" | "nemeth" | "refreshableBraille" | "index" | "pageNavigation" | "skipContent" | "breadcrumbs" | "searchable" | "fullTextSearch" | "multilingualText" | "translatedText" | "glossary" | "signLanguageInterpretation" | "visualLanguage" | "protractor" | "ruler" | "graph" | "graphingCalculator" | "periodicTable" | "formulaSheet" | "answerMasking" | "itemGlossary" | "tutorialAvailable")[];
+export declare const ALL_STANDARD_ACCESS_FEATURES: ("transcript" | "braille" | "textToSpeech" | "calculator" | "graph" | "periodicTable" | "ruler" | "protractor" | "answerEliminator" | "signLanguage" | "readAloud" | "strikethrough" | "magnification" | "screenMagnifier" | "zoomable" | "highContrastDisplay" | "highContrastAudio" | "colorContrast" | "invertColors" | "displayTransformability" | "largePrint" | "fontEnlargement" | "resizeText" | "alternativeText" | "longDescription" | "describedMath" | "tactileGraphic" | "tactileObject" | "audioDescription" | "humanVoice" | "syntheticVoice" | "speechRate" | "speechVolume" | "voicePitch" | "captions" | "closedCaptions" | "openCaptions" | "subtitles" | "audioControl" | "noBackgroundAudio" | "keyboardControl" | "mouseControl" | "touchControl" | "voiceControl" | "switchControl" | "eyeGazeControl" | "singleSwitchAccess" | "stickyKeys" | "keyboardShortcuts" | "timingControl" | "unlimitedTime" | "extendedTime" | "pauseControl" | "simplifiedLanguage" | "reducedComplexity" | "structuralNavigation" | "tableOfContents" | "reducedDistraction" | "noFlashing" | "pauseAnimation" | "annotations" | "bookmarking" | "highlighting" | "guidedNavigation" | "thesaurus" | "spellingAssistance" | "grammarAssistance" | "lineSpacing" | "wordSpacing" | "letterSpacing" | "fontFamily" | "readingMask" | "readingGuide" | "readingRuler" | "wordHighlighting" | "lineHighlighting" | "focusIndicator" | "printableResource" | "nemeth" | "refreshableBraille" | "index" | "pageNavigation" | "skipContent" | "breadcrumbs" | "searchable" | "fullTextSearch" | "multilingualText" | "translatedText" | "glossary" | "signLanguageInterpretation" | "visualLanguage" | "graphingCalculator" | "formulaSheet" | "answerMasking" | "itemGlossary" | "tutorialAvailable")[];
 /**
  * Example PNP configurations for common accessibility needs
  * These are NOT official profiles but illustrative examples showing