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

package/dist/services/section-controller-types.d.ts

@@ -1,3 +1,12 @@
+import type { FormativeFeedbackReveal, FormativeMasteryRollup, FormativeSectionProjection, FormativeTryOutcome } from "@pie-players/pie-players-shared/formative";
+import type { MediaTimeSource, TimedMediaDegradation, TimedMediaSectionProjection, TimedMediaValidationError } from "@pie-players/pie-players-shared/timed-media";
+import type { SectionControllerSessionState } from "@pie-players/pie-players-shared/types";
+/**
+ * Re-exported so every existing import site keeps its specifier. The shape is
+ * canonical in `@pie-players/pie-players-shared/types`, beside
+ * `AssessmentSection` and the delivery slices it carries.
+ */
+export type { SectionControllerSessionState };
 export interface SectionControllerKey {
     assessmentId: string;
     sectionId: string;
@@ -62,11 +71,6 @@ export interface SectionControllerRuntimeState {
      */
     loadedRenderables?: ReadonlyArray<SectionControllerLoadedRenderable>;
 }
-export interface SectionControllerSessionState {
-    currentItemIndex?: number;
-    visitedItemIdentifiers?: string[];
-    itemSessions: Record<string, unknown>;
-}
 type SectionControllerEventBase = {
     timestamp: number;
 };
@@ -156,7 +160,100 @@ export type SectionControllerSectionErrorEvent = SectionControllerEventBase & {
     contentKind?: "item" | "passage" | "rubric" | "unknown";
     currentItemIndex: number;
 };
-export type SectionControllerEvent = SectionControllerItemSessionDataChangedEvent | SectionControllerItemSessionMetaChangedEvent | SectionControllerItemSelectedEvent | SectionControllerSectionNavigationChangedEvent | SectionControllerSectionSessionAppliedEvent | SectionControllerContentLoadedEvent | SectionControllerItemPlayerErrorEvent | SectionControllerItemCompleteChangedEvent | SectionControllerSectionLoadingCompleteEvent | SectionControllerSectionItemsCompleteChangedEvent | SectionControllerSectionErrorEvent;
+export type SectionControllerFormativeTryRecordedEvent = SectionControllerEventBase & {
+    type: "formative-try-recorded";
+    itemId: string;
+    canonicalItemId: string;
+    tryCount: number;
+    outcome: FormativeTryOutcome;
+    /** Whether feedback is now on screen for this item. */
+    revealed: boolean;
+    currentItemIndex: number;
+};
+/**
+ * The reveal state changed without a Try being recorded: a learner dismissed
+ * feedback to edit again, or a host forced a reveal or withdrew one.
+ *
+ * A Try that reveals reports through `formative-try-recorded`, which carries its
+ * own `revealed`. This event is for every other transition.
+ */
+export type SectionControllerFormativeRevealChangedEvent = SectionControllerEventBase & {
+    type: "formative-reveal-changed";
+    itemId: string;
+    canonicalItemId: string;
+    revealed: boolean;
+    /** Reveal level in force, when a host overrode the policy's. */
+    feedback?: FormativeFeedbackReveal;
+    /** Tries already spent; none of these transitions consume one. */
+    tryCount: number;
+    source: "learner" | "host";
+    currentItemIndex: number;
+};
+export type SectionControllerSectionMasteryChangedEvent = SectionControllerEventBase & {
+    type: "section-mastery-changed";
+    mastery: FormativeMasteryRollup;
+    currentItemIndex: number;
+};
+/**
+ * Cue state changed: a cue activated, a gate released, or the section's
+ * aggregate completion flipped.
+ *
+ * Deliberately not emitted for media position. A `timeupdate` fires about four
+ * times a second and moves nothing a layout renders — the media element draws its
+ * own clock — so position is recorded in the session slice and reported here only
+ * through the cue transitions it caused.
+ */
+export type SectionControllerTimedMediaCueChangedEvent = SectionControllerEventBase & {
+    type: "timed-media-cue-changed";
+    /** The cue that activated in this transition, where one did. */
+    activatedCueIdentifier?: string;
+    /** The gate that released in this transition, where one did. */
+    releasedCueIdentifier?: string;
+    activeCueIdentifier?: string;
+    visitedCueIdentifiers: string[];
+    completedCueIdentifiers: string[];
+    /** Canonical ids of every item a visited cue has revealed. */
+    revealedItemIds: string[];
+    /** The gate holding playback, or `null`. */
+    gateCueIdentifier: string | null;
+    mediaCompleted: boolean;
+    aggregateComplete: boolean;
+    currentItemIndex: number;
+};
+/**
+ * Media audio is now running, so any other audio owner must yield.
+ *
+ * Emitted only where playback actually stood: a gate that re-paused on the same
+ * `play` produced no audio. Carries no payload — that media audio started is the
+ * whole fact, and cue state travels on `timed-media-cue-changed`.
+ */
+export type SectionControllerTimedMediaAudioStartedEvent = SectionControllerEventBase & {
+    type: "timed-media-audio-started";
+    currentItemIndex: number;
+};
+/**
+ * A playback policy the attached media time source cannot carry out, reported so
+ * the gap is visible rather than silent. Cues still fire and state is still
+ * recorded; only enforcement is lost.
+ */
+export type SectionControllerTimedMediaPolicyDegradedEvent = SectionControllerEventBase & {
+    type: "timed-media-policy-degraded";
+    degradations: TimedMediaDegradation[];
+    currentItemIndex: number;
+};
+/**
+ * Authored `timedMedia` this section cannot deliver — an unresolvable
+ * `stimulusRef`, a cue naming an item the section does not hold, a gate on
+ * correctness with no `onUnknownCorrectness`. The section still renders, as an
+ * ordinary section with every item visible, because cues that silently never fire
+ * is the failure mode this contract exists to avoid.
+ */
+export type SectionControllerTimedMediaInvalidEvent = SectionControllerEventBase & {
+    type: "timed-media-invalid";
+    errors: TimedMediaValidationError[];
+    currentItemIndex: number;
+};
+export type SectionControllerEvent = SectionControllerItemSessionDataChangedEvent | SectionControllerItemSessionMetaChangedEvent | SectionControllerItemSelectedEvent | SectionControllerSectionNavigationChangedEvent | SectionControllerSectionSessionAppliedEvent | SectionControllerContentLoadedEvent | SectionControllerItemPlayerErrorEvent | SectionControllerItemCompleteChangedEvent | SectionControllerSectionLoadingCompleteEvent | SectionControllerSectionItemsCompleteChangedEvent | SectionControllerSectionErrorEvent | SectionControllerFormativeTryRecordedEvent | SectionControllerFormativeRevealChangedEvent | SectionControllerSectionMasteryChangedEvent | SectionControllerTimedMediaCueChangedEvent | SectionControllerTimedMediaAudioStartedEvent | SectionControllerTimedMediaPolicyDegradedEvent | SectionControllerTimedMediaInvalidEvent;
 export type SectionControllerEventType = SectionControllerEvent["type"];
 /**
  * Host-facing controller for a single section cohort.
@@ -295,6 +392,121 @@ export interface SectionControllerHandle {
      * is what the strategy load/save methods exchange.
      */
     configureSessionPersistence?(config: SectionSessionPersistenceConfig): void | Promise<void>;
+    /**
+     * Record one Try for an item: derive correctness from the element outcomes,
+     * increment the Try count, and reveal feedback if the item's resolved
+     * formative policy says so.
+     *
+     * `outcomes` is what `pie-item-player.provideScore()` returned. The caller
+     * does not interpret it — correctness derivation belongs to the controller so
+     * one aggregation policy applies everywhere.
+     *
+     * No-op when the item's policy is disabled, when feedback is already
+     * revealed, or when Tries are spent, which makes a double submit safe.
+     */
+    recordFormativeTry?(args: {
+        itemId: string;
+        outcomes?: unknown[];
+    }): void;
+    /**
+     * Dismiss a revealed item's feedback and reopen it for editing. Withdrawing
+     * the reveal is what withdraws the `mode: "evaluate"` projection.
+     *
+     * The learner action, so it respects the Try budget: no-op when nothing is
+     * revealed or Tries are spent. Use `hideFormativeItem` for host authority.
+     */
+    retryFormativeItem?(args: {
+        itemId: string;
+    }): void;
+    /**
+     * Reveal an item on host authority — a teacher-driven "show the answer".
+     *
+     * Spends no Try and ignores the Try budget and `revealOn`, none of which bound
+     * a decision the host has already taken. Works on an item with no Try yet.
+     *
+     * `feedback` is stated rather than taken from the policy, because a reveal
+     * under `feedback: "none"` would project nothing.
+     */
+    revealFormativeItem?(args: {
+        itemId: string;
+        feedback: "correctness" | "solution";
+    }): void;
+    /**
+     * Withdraw a reveal on host authority. Unlike `retryFormativeItem` this
+     * ignores the Try budget, so a host that revealed a spent item can put it
+     * back.
+     */
+    hideFormativeItem?(args: {
+        itemId: string;
+    }): void;
+    /**
+     * The section's formative projection — resolved policies, per-item state, and
+     * the mastery rollup.
+     *
+     * `null` when no item in the section delivers formatively. The same
+     * projection rides on the composition model, so layouts normally read it from
+     * there rather than calling this.
+     */
+    getFormativeProjection?(): FormativeSectionProjection | null;
+    /**
+     * Bind the section's Media Time Source — the only way it reaches media.
+     *
+     * Called by the stimulus card once it has a media element to adapt, and
+     * callable directly by a host that supplies its own port: a third-party embed,
+     * a remote-controlled player, anything that can report time. That is the point
+     * of the port. Attaching replaces any previous source.
+     *
+     * The port declares `canPause` / `canRestrictSeeking`; where a capability is
+     * missing the matching policy degrades to advisory and the controller emits
+     * `timed-media-policy-degraded` rather than appearing to enforce.
+     *
+     * No-op on a section that carries no valid `timedMedia`.
+     */
+    attachMediaTimeSource?(source: MediaTimeSource, options?: {
+        /**
+         * `"native-adapter"` marks the stimulus card's own discovery, which never
+         * displaces a source a host attached explicitly.
+         */
+        origin?: "native-adapter" | "host";
+        /**
+         * The renderable the source was found in. Checked against the renderable
+         * `stimulusRef` resolved to, so a second video passage's adapter cannot
+         * drive the timeline. Omitted by a host attaching its own port, which names
+         * no renderable and is taken at its word.
+         */
+        renderableId?: string;
+    }): void;
+    /**
+     * Release the current source. Cue state is kept; nothing advances it.
+     *
+     * A `"native-adapter"` detach is ignored while a host-attached source is live:
+     * the stimulus card tears its adapter down whenever its content re-renders, and
+     * that must not take a host's own player with it.
+     */
+    detachMediaTimeSource?(options?: {
+        origin?: "native-adapter" | "host";
+    }): void;
+    /**
+     * Silence media audio so read-aloud can speak over the same stimulus.
+     *
+     * One half of the TTS/media handoff. The section stops media and announces
+     * `timed-media-audio-started` when media audio resumes; the toolkit owns the
+     * policy, because only the toolkit holds both the TTS service and the section.
+     *
+     * Returns whether media audio is now silent — `false` for a playing source that
+     * reports no `canPause`, where the overlap stands rather than read-aloud being
+     * withheld.
+     */
+    pauseMediaForCompetingAudio?(): boolean;
+    /**
+     * The section's timed-media projection — cues, enforcement, revealed items and
+     * the gate currently holding playback.
+     *
+     * `null` when the section is not timed media or its `timedMedia` failed
+     * validation. The same projection rides on the composition model, so layouts
+     * read it from there rather than calling this.
+     */
+    getTimedMediaProjection?(): TimedMediaSectionProjection | null;
 }
 export interface SectionControllerFactoryDefaults {
     createDefaultController: () => SectionControllerHandle | Promise<SectionControllerHandle>;
@@ -302,4 +514,3 @@ export interface SectionControllerFactoryDefaults {
 export interface SectionPersistenceFactoryDefaults {
     createDefaultPersistence: () => SectionSessionPersistenceStrategy | Promise<SectionSessionPersistenceStrategy>;
 }
-export {};

package/dist/services/selection-action.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Host-supplied actions on a text selection.
+ *
+ * The contract between a selection gateway and whoever composes it. The gateway
+ * renders the actions it is handed and knows nothing about what they do; the
+ * composer knows which capabilities exist and pairs them up. That split is what
+ * keeps a gateway from naming a dictionary, and what lets a host contribute an
+ * action for a capability PIE does not ship.
+ */
+/** What the gateway hands an action when the learner activates it. */
+export interface ToolSelectionContext {
+    /** The selected text, trimmed and whitespace-collapsed by the gateway. */
+    text: string;
+    /**
+     * The live range, or `null` when the gateway has already lost it.
+     *
+     * An action that only needs the words should use `text`; the range is for an
+     * action that has to know where in the content the words were.
+     */
+    range: Range | null;
+}
+export interface ToolSelectionAction {
+    /** Stable id, used as the button's key and its `data-pie-selection-action`. */
+    id: string;
+    /** Visible and accessible name. */
+    label: string;
+    /**
+     * Inline SVG markup for the button face.
+     *
+     * Markup rather than an icon name because a gateway has no icon registry, and
+     * the composer already resolves names through the toolkit's own map. Rendered
+     * into the gateway's shadow root and treated as trusted composer-authored
+     * markup, on the same footing as the shell's own action icons — never a place
+     * to put anything that reached the composer from content or a service.
+     */
+    iconSvg?: string;
+    /** Longer tooltip, when the label alone reads as terse in a strip of icons. */
+    tooltip?: string;
+    /**
+     * Whether to offer the action at all, asked on each render.
+     *
+     * An action whose target capability is not available answers `false` rather
+     * than being offered and failing: an affordance that does nothing costs a
+     * learner a keystroke and their confidence in the rest of the strip.
+     */
+    isAvailable?: () => boolean;
+    /** Perform the action. */
+    run: (selection: ToolSelectionContext) => void;
+}

package/dist/services/selection-action.js

@@ -0,0 +1,10 @@
+/**
+ * Host-supplied actions on a text selection.
+ *
+ * The contract between a selection gateway and whoever composes it. The gateway
+ * renders the actions it is handed and knows nothing about what they do; the
+ * composer knows which capabilities exist and pairs them up. That split is what
+ * keeps a gateway from naming a dictionary, and what lets a host contribute an
+ * action for a capability PIE does not ship.
+ */
+export {};

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

@@ -20,7 +20,7 @@
  *
  * Part of PIE Assessment Toolkit.
  */
-import { normalizeMediaFragment, normalizeMediaSources, trimmedOrUndefined, } from "./catalog-media.js";
+import { isUnsupportedMediaAssetVersion, 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";
 /**
@@ -46,6 +46,10 @@ export function resolveSpokenAudioMedia(card) {
         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;
     }
+    if (isUnsupportedMediaAssetVersion(media.version)) {
+        console.warn(`[spoken-audio] card's media declares version ${String(media.version)}, which this build does not render; the 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.

package/dist/services/tool-context.d.ts

@@ -125,14 +125,15 @@ export declare function isRubricContext(context: ToolContext): context is Rubric
  * Type guard to check if context is at element level
  */
 export declare function isElementContext(context: ToolContext): context is ElementToolContext;
-/**
- * Helper to extract text content from an item or element for analysis
- */
+/** The plain text a context carries, tags removed. */
 export declare function extractTextContent(context: ToolContext): string;
 /**
- * Helper to check if context contains mathematical content
- * (Basic heuristic - can be overridden by tools)
+ * The authored markup a context carries, tags intact.
+ *
+ * For indicators that live in the markup rather than in the prose — `<math>`
+ * above all, whose whole signal is the element name.
  */
+export declare function extractMarkupContent(context: ToolContext): string;
 export declare function hasMathContent(context: ToolContext): boolean;
 /**
  * Helper to check if context contains choice-based interactions