@pie-players/pie-players-shared 0.3.66 → 0.3.68

package/README.md

@@ -19,12 +19,71 @@ Supported subpaths are declared in `package.json`:
 - `@pie-players/pie-players-shared/security`
 - `@pie-players/pie-players-shared/object`
 - `@pie-players/pie-players-shared/types`
+- `@pie-players/pie-players-shared/formative`
+- `@pie-players/pie-players-shared/timed-media`
 - `@pie-players/pie-players-shared/pie`
 - `@pie-players/pie-players-shared/pie/tag-names`
 - `@pie-players/pie-players-shared/loaders`
 - `@pie-players/pie-players-shared/server/npm-registry`
 - `@pie-players/pie-players-shared/i18n`
 
+## Formative Delivery
+
+`@pie-players/pie-players-shared/formative` holds the policy resolution, outcome
+aggregation, Try-state reducer, item view, and mastery rollup that
+`pie-section-player` drives. It is pure — no DOM, no timers, no element registry
+— so it is testable without a browser and importable by an adapter that has no
+player.
+
+```ts
+import {
+  aggregateFormativeOutcome,
+  resolveFormativePolicy,
+  resolveFormativeItemView,
+  rollupFormativeMastery,
+} from "@pie-players/pie-players-shared/formative";
+```
+
+The authored half — `FormativeDeliveryPolicy` on `AssessmentSection` and
+`FormativeItemPolicy` on `AssessmentItemRef` — is re-exported from the package
+root and from `/types`, beside the section types it annotates.
+
+The contract is [`docs/prds/formative-delivery-contract.md`](../../docs/prds/formative-delivery-contract.md),
+including the QTI 3 mapping and why PIE says **Try** rather than "attempt".
+
+## Timed Media
+
+`@pie-players/pie-players-shared/timed-media` holds the timed-media section
+vocabulary, its validation, the cue reduction, the session slice, and the **Media
+Time Source** port that a section reaches media through. Pure apart from
+`createMediaElementTimeSource`, which is inert until called, so the contract stays
+importable in Node beside the rest.
+
+```ts
+import {
+  createMediaElementTimeSource,
+  normalizeTimedMediaSectionData,
+  reduceTimedMediaState,
+  resolveTimedMediaProjection,
+  type MediaTimeSource,
+} from "@pie-players/pie-players-shared/timed-media";
+```
+
+The port is shaped after `HTMLMediaElement` on purpose — a native `<video>`
+satisfies it through the adapter above — with two departures: seeking is
+`seekTo(seconds)` rather than a writable `currentTime`, and `capabilities` declares
+`canPause` / `canRestrictSeeking`, because a source that cannot control playback
+needs a way to say so. A host implementing the port directly needs no PIE element to
+deliver timed media.
+
+The authored half — `sectionType` and `timedMedia` on `AssessmentSection` — is
+re-exported from the package root and from `/types`, beside the section types it
+annotates.
+
+The contract is [`docs/prds/timed-media-section-contract.md`](../../docs/prds/timed-media-section-contract.md),
+including why cue gate conditions name the formative vocabulary and why an
+unenforceable policy degrades to advisory rather than failing closed.
+
 ## Browser ESM Element Contract
 
 The canonical producer-side contract lives with the `pie-elements-ng` package

package/dist/formative/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Formative delivery: Try state, feedback reveal, and section mastery.
+ *
+ * Pure and Node-safe by design — no DOM, no timers, no element registry — so
+ * the contract is testable without a browser and an adapter can import it
+ * without pulling in a player. Everything that touches the DOM stays in
+ * `@pie-players/pie-section-player`.
+ *
+ * Contract: `docs/prds/formative-delivery-contract.md`.
+ */
+export type { FormativeAction, FormativeCorrectness, FormativeDeliveryPolicy, FormativeEnvOverride, FormativeFeedbackReveal, FormativeItemPolicy, FormativeItemState, FormativeItemView, FormativeMasteryRollup, FormativeRevealTiming, FormativeScoredOutcome, FormativeSectionProjection, FormativeSectionSlice, FormativeTryLimit, FormativeTryOutcome, ResolvedFormativePolicy, } from "./types.js";
+export { FORMATIVE_POLICY_DEFAULTS, isFormativeSectionEnabled, resolveFormativePolicies, resolveFormativePolicy, } from "./policy.js";
+export { aggregateFormativeOutcome } from "./outcome.js";
+export { FORMATIVE_ITEM_STATE_VERSION, createFormativeItemState, hideFormativeItem, recordFormativeTry, resolveFormativeItemView, retryFormativeItem, revealFormativeItem, } from "./state.js";
+export { FORMATIVE_MASTERY_VERSION, rollupFormativeMastery } from "./mastery.js";
+export { FORMATIVE_SLICE_VERSION, normalizeFormativeSectionSlice, toFormativeSectionSlice, } from "./session.js";

package/dist/formative/index.js

@@ -0,0 +1,5 @@
+export { FORMATIVE_POLICY_DEFAULTS, isFormativeSectionEnabled, resolveFormativePolicies, resolveFormativePolicy, } from "./policy.js";
+export { aggregateFormativeOutcome } from "./outcome.js";
+export { FORMATIVE_ITEM_STATE_VERSION, createFormativeItemState, hideFormativeItem, recordFormativeTry, resolveFormativeItemView, retryFormativeItem, revealFormativeItem, } from "./state.js";
+export { FORMATIVE_MASTERY_VERSION, rollupFormativeMastery } from "./mastery.js";
+export { FORMATIVE_SLICE_VERSION, normalizeFormativeSectionSlice, toFormativeSectionSlice, } from "./session.js";

package/dist/formative/mastery.d.ts

@@ -0,0 +1,16 @@
+import type { FormativeItemState, FormativeMasteryRollup } from "./types.js";
+export declare const FORMATIVE_MASTERY_VERSION: 1;
+/**
+ * Roll Try outcomes up to the section.
+ *
+ * The denominator is the load-bearing decision. An item whose last outcome was
+ * `"unknown"` — a rubric item, or one whose element ships no controller — is
+ * excluded rather than counted wrong, because counting it wrong would report a
+ * false negative to whatever consumes the rollup. An *untried* item is not
+ * excluded: nothing yet says it cannot be scored, so it keeps the section from
+ * reading as complete after one correct answer.
+ */
+export declare function rollupFormativeMastery(args: {
+    itemIdentifiers: readonly string[];
+    states: Record<string, FormativeItemState>;
+}): FormativeMasteryRollup;

package/dist/formative/mastery.js

@@ -0,0 +1,43 @@
+export const FORMATIVE_MASTERY_VERSION = 1;
+/**
+ * Roll Try outcomes up to the section.
+ *
+ * The denominator is the load-bearing decision. An item whose last outcome was
+ * `"unknown"` — a rubric item, or one whose element ships no controller — is
+ * excluded rather than counted wrong, because counting it wrong would report a
+ * false negative to whatever consumes the rollup. An *untried* item is not
+ * excluded: nothing yet says it cannot be scored, so it keeps the section from
+ * reading as complete after one correct answer.
+ */
+export function rollupFormativeMastery(args) {
+    const identifiers = args.itemIdentifiers ?? [];
+    const totalItems = identifiers.length;
+    let notScorableItems = 0;
+    let masteredItems = 0;
+    let triedItems = 0;
+    let triesToMasteryTotal = 0;
+    for (const identifier of identifiers) {
+        const state = args.states?.[identifier];
+        if (!state)
+            continue;
+        if (state.tryCount > 0)
+            triedItems += 1;
+        if (state.lastOutcome?.correctness === "unknown")
+            notScorableItems += 1;
+        if (typeof state.firstCorrectTry === "number") {
+            masteredItems += 1;
+            triesToMasteryTotal += state.firstCorrectTry;
+        }
+    }
+    const scorableItems = Math.max(0, totalItems - notScorableItems);
+    return {
+        version: FORMATIVE_MASTERY_VERSION,
+        totalItems,
+        scorableItems,
+        masteredItems,
+        triedItems,
+        averageTriesToMastery: masteredItems > 0 ? triesToMasteryTotal / masteredItems : undefined,
+        // A section with nothing scorable is never vacuously complete.
+        complete: scorableItems > 0 && masteredItems === scorableItems,
+    };
+}

package/dist/formative/outcome.d.ts

@@ -0,0 +1,19 @@
+import type { FormativeScoredOutcome, FormativeTryOutcome } from "./types.js";
+/**
+ * Reduce the array `pie-item-player.provideScore()` returns to one Try outcome.
+ *
+ * The aggregation mirrors the policy the persisted API scoring path already
+ * documents (`docs/item-player/scoring-and-rubrics.md`), so a browser-derived
+ * formative result and a server-derived score do not disagree about what a
+ * multi-element item is worth:
+ *
+ * - one scored outcome: `points = score`, `max = max ?? 1`;
+ * - several: the mean of normalized fractions, with `max = 1`;
+ * - none scored: `"unknown"`, no points.
+ *
+ * `provideScore()` returns `undefined` in the slot of any model whose element or
+ * controller was missing, which is exactly the rubric and no-controller case, so
+ * those slots count toward `totalElementCount` and not toward
+ * `scoredElementCount`.
+ */
+export declare function aggregateFormativeOutcome(outcomes: ReadonlyArray<FormativeScoredOutcome | null | undefined> | null): FormativeTryOutcome;

package/dist/formative/outcome.js

@@ -0,0 +1,90 @@
+/**
+ * Full credit is a float comparison, so it needs a tolerance. Averaging
+ * normalized fractions ("1/3 + 1/3 + 1/3") lands a hair under 1 in binary
+ * floating point, and reporting that as partial credit would be a defect
+ * visible to a learner.
+ */
+const FULL_CREDIT_EPSILON = 1e-9;
+function isScored(outcome) {
+    return (!!outcome &&
+        typeof outcome.score === "number" &&
+        Number.isFinite(outcome.score));
+}
+/** A denominator of 0 or a missing `max` both mean "normalized to 1". */
+function denominatorOf(outcome) {
+    const max = outcome.max;
+    return typeof max === "number" && Number.isFinite(max) && max > 0 ? max : 1;
+}
+/**
+ * Retained verbatim for a host rendering its own feedback. Empty slots are
+ * dropped rather than preserved as holes: every real entry identifies its own
+ * model, and `null` in a persisted array carries no information a host could
+ * use.
+ */
+function definedOutcomes(outcomes) {
+    const defined = outcomes.filter((outcome) => !!outcome && typeof outcome === "object");
+    return defined.length > 0 ? defined : undefined;
+}
+function classify(points, max) {
+    if (max <= 0)
+        return "unknown";
+    if (points + FULL_CREDIT_EPSILON >= max)
+        return "correct";
+    if (points <= 0)
+        return "incorrect";
+    return "partial";
+}
+/**
+ * Reduce the array `pie-item-player.provideScore()` returns to one Try outcome.
+ *
+ * The aggregation mirrors the policy the persisted API scoring path already
+ * documents (`docs/item-player/scoring-and-rubrics.md`), so a browser-derived
+ * formative result and a server-derived score do not disagree about what a
+ * multi-element item is worth:
+ *
+ * - one scored outcome: `points = score`, `max = max ?? 1`;
+ * - several: the mean of normalized fractions, with `max = 1`;
+ * - none scored: `"unknown"`, no points.
+ *
+ * `provideScore()` returns `undefined` in the slot of any model whose element or
+ * controller was missing, which is exactly the rubric and no-controller case, so
+ * those slots count toward `totalElementCount` and not toward
+ * `scoredElementCount`.
+ */
+export function aggregateFormativeOutcome(outcomes) {
+    const all = Array.isArray(outcomes) ? outcomes : [];
+    const scored = all.filter(isScored);
+    const totalElementCount = all.length;
+    if (scored.length === 0) {
+        return {
+            correctness: "unknown",
+            scoredElementCount: 0,
+            totalElementCount,
+            elementOutcomes: definedOutcomes(all),
+        };
+    }
+    let points;
+    let max;
+    if (scored.length === 1) {
+        const only = scored[0];
+        max = denominatorOf(only);
+        points = only.score;
+    }
+    else {
+        max = 1;
+        points =
+            scored.reduce((total, outcome) => total + outcome.score / denominatorOf(outcome), 0) / scored.length;
+    }
+    // An element reporting more than its own maximum is an element defect. The
+    // aggregate is a ratio, so an out-of-range input has no meaning here; clamp
+    // rather than let it read as full credit on a partially correct response.
+    const clamped = Math.min(Math.max(points, 0), max);
+    return {
+        correctness: classify(clamped, max),
+        points: clamped,
+        max,
+        scoredElementCount: scored.length,
+        totalElementCount,
+        elementOutcomes: definedOutcomes(all),
+    };
+}

package/dist/formative/policy.d.ts

@@ -0,0 +1,37 @@
+import type { FormativeDeliveryPolicy, FormativeItemPolicy, ResolvedFormativePolicy } from "./types.js";
+/**
+ * Built-in defaults. `enabled: false` is what makes this contract invisible to
+ * every section authored before it: an absent `formative` field resolves to a
+ * disabled policy, and a disabled policy produces no state, no projection and
+ * no control.
+ *
+ * `maxTries: 1` matches QTI 3's `qti-item-session-control@max-attempts` default.
+ */
+export declare const FORMATIVE_POLICY_DEFAULTS: ResolvedFormativePolicy;
+/**
+ * Merge built-in defaults, the section policy, and one item ref's override, in
+ * that order. Each field overrides independently, which is the order QTI 3 uses
+ * for `qti-item-session-control` on a section and on an item ref.
+ *
+ * Unrecognized values fall through to the layer beneath rather than failing the
+ * section: authored policy is host-supplied data, and a typo in one field should
+ * not cost the learner the whole item.
+ */
+export declare function resolveFormativePolicy(sectionPolicy?: FormativeDeliveryPolicy | null, itemPolicy?: FormativeItemPolicy | null): ResolvedFormativePolicy;
+/**
+ * Resolve one policy per item in section order.
+ *
+ * Keyed by the identifier the caller supplies, which in the section runtime is
+ * the canonical item id — the same key `itemSessions` and the completion map
+ * use, so a formative state and an item session are always addressable by one
+ * id.
+ */
+export declare function resolveFormativePolicies(args: {
+    sectionPolicy?: FormativeDeliveryPolicy | null;
+    items: ReadonlyArray<{
+        identifier: string;
+        policy?: FormativeItemPolicy | null;
+    }>;
+}): Record<string, ResolvedFormativePolicy>;
+/** True when at least one item in the section delivers formatively. */
+export declare function isFormativeSectionEnabled(policies: Record<string, ResolvedFormativePolicy>): boolean;

package/dist/formative/policy.js

@@ -0,0 +1,86 @@
+/**
+ * Built-in defaults. `enabled: false` is what makes this contract invisible to
+ * every section authored before it: an absent `formative` field resolves to a
+ * disabled policy, and a disabled policy produces no state, no projection and
+ * no control.
+ *
+ * `maxTries: 1` matches QTI 3's `qti-item-session-control@max-attempts` default.
+ */
+export const FORMATIVE_POLICY_DEFAULTS = {
+    enabled: false,
+    maxTries: 1,
+    feedback: "correctness",
+    revealOn: "on-try",
+};
+function normalizeTryLimit(value) {
+    if (value === "unlimited")
+        return "unlimited";
+    if (typeof value !== "number" || !Number.isFinite(value))
+        return undefined;
+    const rounded = Math.trunc(value);
+    // Zero and negatives are meaningless here rather than shorthand for
+    // unlimited. QTI spells unlimited as `max-attempts="0"`; the adapter
+    // translates, this contract does not overload the number.
+    return rounded >= 1 ? rounded : undefined;
+}
+function normalizeFeedback(value) {
+    return value === "none" || value === "correctness" || value === "solution"
+        ? value
+        : undefined;
+}
+function normalizeRevealTiming(value) {
+    return value === "on-try" || value === "on-final-try" ? value : undefined;
+}
+/**
+ * Merge built-in defaults, the section policy, and one item ref's override, in
+ * that order. Each field overrides independently, which is the order QTI 3 uses
+ * for `qti-item-session-control` on a section and on an item ref.
+ *
+ * Unrecognized values fall through to the layer beneath rather than failing the
+ * section: authored policy is host-supplied data, and a typo in one field should
+ * not cost the learner the whole item.
+ */
+export function resolveFormativePolicy(sectionPolicy, itemPolicy) {
+    const enabled = typeof itemPolicy?.enabled === "boolean"
+        ? itemPolicy.enabled
+        : typeof sectionPolicy?.enabled === "boolean"
+            ? sectionPolicy.enabled
+            : FORMATIVE_POLICY_DEFAULTS.enabled;
+    const maxTries = normalizeTryLimit(itemPolicy?.maxTries) ??
+        normalizeTryLimit(sectionPolicy?.maxTries) ??
+        FORMATIVE_POLICY_DEFAULTS.maxTries;
+    const feedback = normalizeFeedback(itemPolicy?.feedback) ??
+        normalizeFeedback(sectionPolicy?.feedback) ??
+        FORMATIVE_POLICY_DEFAULTS.feedback;
+    const requestedRevealOn = normalizeRevealTiming(itemPolicy?.revealOn) ??
+        normalizeRevealTiming(sectionPolicy?.revealOn) ??
+        FORMATIVE_POLICY_DEFAULTS.revealOn;
+    // `"on-final-try"` has no referent under unlimited Tries — there is no final
+    // Try to reveal on — so it resolves to the only reading that keeps feedback
+    // reachable.
+    const revealOn = requestedRevealOn === "on-final-try" && maxTries === "unlimited"
+        ? "on-try"
+        : requestedRevealOn;
+    return { enabled, maxTries, feedback, revealOn };
+}
+/**
+ * Resolve one policy per item in section order.
+ *
+ * Keyed by the identifier the caller supplies, which in the section runtime is
+ * the canonical item id — the same key `itemSessions` and the completion map
+ * use, so a formative state and an item session are always addressable by one
+ * id.
+ */
+export function resolveFormativePolicies(args) {
+    const resolved = {};
+    for (const item of args.items) {
+        if (!item?.identifier)
+            continue;
+        resolved[item.identifier] = resolveFormativePolicy(args.sectionPolicy, item.policy);
+    }
+    return resolved;
+}
+/** True when at least one item in the section delivers formatively. */
+export function isFormativeSectionEnabled(policies) {
+    return Object.values(policies).some((policy) => policy.enabled);
+}

package/dist/formative/session.d.ts

@@ -0,0 +1,19 @@
+import type { FormativeItemState, FormativeSectionSlice } from "./types.js";
+export declare const FORMATIVE_SLICE_VERSION: 1;
+export declare function toFormativeSectionSlice(states: Record<string, FormativeItemState>): FormativeSectionSlice;
+/**
+ * Validate a persisted slice against the section it is being restored into.
+ *
+ * Returns `null` for a slice this build cannot read, which the caller treats as
+ * "start formative state clean". Rejection is deliberately narrow: it discards
+ * formative progress and nothing else, so a version bump here never costs a
+ * learner their responses — item sessions travel in the same snapshot and are
+ * normalized separately.
+ *
+ * An absent slice is `null` too, and indistinguishable from a pre-formative
+ * save, which is what keeps existing snapshots valid.
+ */
+export declare function normalizeFormativeSectionSlice(args: {
+    slice: unknown;
+    allowedItemIdentifiers: readonly string[];
+}): Record<string, FormativeItemState> | null;

package/dist/formative/session.js

@@ -0,0 +1,113 @@
+import { FORMATIVE_ITEM_STATE_VERSION } from "./state.js";
+export const FORMATIVE_SLICE_VERSION = 1;
+const CORRECTNESS_VALUES = [
+    "correct",
+    "partial",
+    "incorrect",
+    "unknown",
+];
+function readFiniteNumber(value) {
+    return typeof value === "number" && Number.isFinite(value)
+        ? value
+        : undefined;
+}
+function readNonNegativeInteger(value) {
+    const numeric = readFiniteNumber(value);
+    if (numeric === undefined)
+        return undefined;
+    const rounded = Math.trunc(numeric);
+    return rounded >= 0 ? rounded : undefined;
+}
+function normalizeOutcome(value) {
+    if (!value || typeof value !== "object")
+        return undefined;
+    const raw = value;
+    const correctness = CORRECTNESS_VALUES.find((candidate) => candidate === raw.correctness);
+    if (!correctness)
+        return undefined;
+    return {
+        correctness,
+        points: readFiniteNumber(raw.points),
+        max: readFiniteNumber(raw.max),
+        scoredElementCount: readNonNegativeInteger(raw.scoredElementCount) ?? 0,
+        totalElementCount: readNonNegativeInteger(raw.totalElementCount) ?? 0,
+        elementOutcomes: normalizeElementOutcomes(raw.elementOutcomes),
+    };
+}
+/**
+ * Element outcomes are element-shaped by contract, so validation stops at "an
+ * array of objects". Reaching further would mean this module deciding what an
+ * element's outcome may contain, which is the element's business.
+ */
+function normalizeElementOutcomes(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const entries = value.filter((entry) => !!entry && typeof entry === "object" && !Array.isArray(entry));
+    return entries.length > 0 ? entries : undefined;
+}
+function normalizeRevealOverride(value) {
+    return value === "correctness" || value === "solution" || value === "none"
+        ? value
+        : undefined;
+}
+function normalizeItemState(itemIdentifier, value) {
+    if (!value || typeof value !== "object")
+        return null;
+    const raw = value;
+    if (raw.version !== FORMATIVE_ITEM_STATE_VERSION)
+        return null;
+    const tryCount = readNonNegativeInteger(raw.tryCount);
+    if (tryCount === undefined)
+        return null;
+    const firstCorrectTry = readNonNegativeInteger(raw.firstCorrectTry);
+    return {
+        version: FORMATIVE_ITEM_STATE_VERSION,
+        itemIdentifier,
+        tryCount,
+        revealed: raw.revealed === true,
+        lastOutcome: normalizeOutcome(raw.lastOutcome),
+        firstCorrectTry: firstCorrectTry !== undefined && firstCorrectTry >= 1
+            ? firstCorrectTry
+            : undefined,
+        revealOverride: normalizeRevealOverride(raw.revealOverride),
+    };
+}
+export function toFormativeSectionSlice(states) {
+    return {
+        version: FORMATIVE_SLICE_VERSION,
+        items: { ...states },
+    };
+}
+/**
+ * Validate a persisted slice against the section it is being restored into.
+ *
+ * Returns `null` for a slice this build cannot read, which the caller treats as
+ * "start formative state clean". Rejection is deliberately narrow: it discards
+ * formative progress and nothing else, so a version bump here never costs a
+ * learner their responses — item sessions travel in the same snapshot and are
+ * normalized separately.
+ *
+ * An absent slice is `null` too, and indistinguishable from a pre-formative
+ * save, which is what keeps existing snapshots valid.
+ */
+export function normalizeFormativeSectionSlice(args) {
+    const { slice } = args;
+    if (!slice || typeof slice !== "object")
+        return null;
+    const raw = slice;
+    if (raw.version !== FORMATIVE_SLICE_VERSION)
+        return null;
+    if (!raw.items || typeof raw.items !== "object")
+        return null;
+    const allowed = new Set(args.allowedItemIdentifiers ?? []);
+    const normalized = {};
+    for (const [itemIdentifier, entry] of Object.entries(raw.items)) {
+        if (!allowed.has(itemIdentifier))
+            continue;
+        const state = normalizeItemState(itemIdentifier, entry);
+        if (!state)
+            continue;
+        normalized[itemIdentifier] = state;
+    }
+    return normalized;
+}

package/dist/formative/state.d.ts

@@ -0,0 +1,60 @@
+import type { FormativeFeedbackReveal, FormativeItemState, FormativeItemView, FormativeTryOutcome, ResolvedFormativePolicy } from "./types.js";
+export declare const FORMATIVE_ITEM_STATE_VERSION: 1;
+export declare function createFormativeItemState(itemIdentifier: string): FormativeItemState;
+/**
+ * Record one Try.
+ *
+ * Idempotent against a double submit: a Try is only counted when the current
+ * state can be checked, so a second click landing before the projection
+ * round-trips is dropped rather than spending a Try.
+ */
+export declare function recordFormativeTry(args: {
+    state?: FormativeItemState;
+    itemIdentifier: string;
+    policy: ResolvedFormativePolicy;
+    outcome: FormativeTryOutcome;
+}): FormativeItemState;
+/**
+ * Dismiss a reveal and reopen the item for editing. Withdrawing `revealed` is
+ * what withdraws the env override, so the item returns to the section's own
+ * mode.
+ *
+ * A learner action, so it respects the Try budget: an item with none left keeps
+ * its feedback on screen. `hideFormativeItem` is the host-authority version.
+ */
+export declare function retryFormativeItem(args: {
+    state?: FormativeItemState;
+    policy: ResolvedFormativePolicy;
+}): FormativeItemState | undefined;
+/**
+ * Reveal on host authority — a teacher-driven "show the answer".
+ *
+ * Spends no Try and ignores the Try budget and `revealOn`, because none of those
+ * bound a decision the host has already taken. `feedback` is required rather
+ * than defaulted from the policy: a forced reveal under `feedback: "none"` would
+ * project nothing, so the caller states what to show.
+ *
+ * Works on an item with no Try yet. The element renders evaluate mode over
+ * whatever response is there, including none, which is what "show the answer"
+ * means before the learner has answered.
+ */
+export declare function revealFormativeItem(args: {
+    state?: FormativeItemState;
+    itemIdentifier: string;
+    policy: ResolvedFormativePolicy;
+    feedback: Exclude<FormativeFeedbackReveal, "none">;
+}): FormativeItemState;
+/**
+ * Withdraw a reveal on host authority. Unlike a learner retry this ignores the
+ * Try budget: a host that revealed an item with no Tries left must be able to
+ * put it back.
+ */
+export declare function hideFormativeItem(args: {
+    state?: FormativeItemState;
+    policy: ResolvedFormativePolicy;
+}): FormativeItemState | undefined;
+/** Derive everything a rendering component needs from policy plus state. */
+export declare function resolveFormativeItemView(args: {
+    policy: ResolvedFormativePolicy;
+    state?: FormativeItemState;
+}): FormativeItemView;