@step-wise/input-exercises 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 Step-Wise
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,245 @@
+# @step-wise/input-exercises
+
+Build educational exercises that interpret learner input, check it against generated parameters, update practiced skills, and track whether the exercise was solved or given up.
+
+This package specializes the reducer model from [@step-wise/exercise-definition](https://www.npmjs.com/package/@step-wise/exercise-definition). Exercise authors describe how to generate a problem and check an answer; the builders in this package supply the solo- and group-reducers.
+
+
+## Installation
+
+```bash
+npm install @step-wise/input-exercises
+```
+
+
+## Mono exercises
+
+A `MonoExercise` checks one problem as a whole. The input is either correct or it's not. Create one with `buildMonoExercise`:
+
+```ts
+import { buildMonoExercise, getInput } from '@step-wise/input-exercises'
+
+type Parameters = { left: number, right: number }
+type Solution = { answer: number }
+
+const addition = buildMonoExercise<Parameters, Solution>({
+	metadata: { skill: 'addition' },
+	generateParameters: example => example ? { left: 2, right: 3 } : { left: 7, right: 8 },
+	getSolution: parameters => ({ answer: parameters.left + parameters.right }),
+	checkInput: data => getInput('answer', data, 'number') === data.solution?.answer,
+})
+```
+
+An input exercise specification commonly contains:
+
+- `metadata` includes the practiced `skill` or a more involved skill `setup`.
+- `generateParameters(example)` creates the fixed problem parameters. It generally uses randomization and may be synchronous or asynchronous.
+- `getSolution(parameters, inputDependency, staticSolution)` builds the solution. Exercises without input dependencies normally use only `parameters`.
+- `checkInput(data)` decides whether the interpreted learner input is correct. Its data includes the raw and interpreted input, current input dependency, and corresponding solution. It may return either a boolean or `{ correct, report? }`, immediately or through a promise.
+
+Only `metadata` and `checkInput` are required. Omitting `generateParameters` uses an empty object.
+
+Returning a structured result lets grading retain plain-data details about the transition without putting them in the exercise state:
+
+```ts
+checkInput: data => ({
+	correct: getInput('answer', data, 'number') === data.solution?.answer,
+	report: { unitCorrect: true },
+})
+```
+
+Existing boolean checks are normalized to `{ correct }` and therefore produce no report. A solo reducer exposes the report directly in its result. A group reducer collects reports by user ID. If `checkInput` omits its report, the reducer result omits it too; an explicit empty object remains an explicit report.
+
+`buildMonoExercise` creates both `processSoloAction` and `processGroupActions`. Consumers therefore do not need separate exercise definitions for solo and group use.
+
+
+## Step exercises
+
+A `StepExercise` first lets the learner answer the complete problem. If the learner gives up, it splits the problem into guided steps:
+
+```ts
+import {buildStepExercise, createStepExerciseMetadata, getInput } from '@step-wise/input-exercises'
+
+const multiplication = buildStepExercise({
+	metadata: {
+		...createStepExerciseMetadata(['multiply-ones', 'multiply-tens']),
+		skill: 'multiplication',
+	},
+	generateParameters: () => ({ left: 12, right: 3 }),
+	getSolution: ({ left, right }) => ({ answer: left * right }),
+	checkInput: (data, step) => {
+		const answer = getInput('answer', data, 'number')
+		switch (step) {
+			case 1: return answer === 6
+			case 2: return answer === 30
+			default: return answer === data.solution?.answer
+		}
+	},
+})
+```
+
+Steps are numbered from `1`. The unsplit main problem uses step `0`. `getCurrentStep(state)` returns this number.
+
+`createStepExerciseMetadata(steps)` stores the step structure and combines its defined skills into a skill setup. A step may be `undefined` when it does not have a separately tracked skill.
+
+
+## Substeps
+
+A step can contain an array of substeps:
+
+```ts
+const metadata = createStepExerciseMetadata(['expand-brackets', ['combine-like-terms', 'simplify-coefficients']])
+```
+
+A substep array must contain at least two entries; otherwise it should be an ordinary step. Substeps are numbered from `1`. For the main problem and ordinary steps, `substep` is `0`:
+
+```ts
+checkInput: (data, step, substep) => {
+	if (step === 0) return checkCompleteProblem(data)
+	if (step === 1) return checkExpansion(data)
+	if (substep === 1) return checkLikeTerms(data)
+	return checkCoefficients(data)
+}
+```
+
+One input may solve one or more substeps if `checkInput` accepts that same input for them. Attempts are stored per step, not separately for every substep.
+
+
+## Custom value types
+
+An exercise can opt into domain-specific behavior through its optional `valueTypes` registry. Each value type may provide input interpretation, parameter serialization, equality, or any combination of those capabilities.
+
+```ts
+const exercise = buildMonoExercise({
+	metadata: { skill: 'algebra' },
+	valueTypes: mathematicsValueTypes,
+	generateParameters: () => ({ expression: createExpression() }),
+	checkInput: data => compareInputs('answer', data),
+})
+```
+
+The builders combine the supplied registry with the fundamental Integer and MultipleChoice value types, validate it, and capture its adapters privately. The built exercise exposes `valueOperations` with `serialize`, `deserialize`, `interpretInput`, `toInputValue`, and `areValuesEqual`; consumers never need the registry or its adapters. Generated parameters and submitted actions use the same captured operations internally. An omitted registry therefore still provides Integer and MultipleChoice interpretation and equality without exercise-level configuration.
+
+Use `combineValueTypes` from [@step-wise/value-types](https://www.npmjs.com/package/@step-wise/value-types) when an exercise needs more than one domain. Duplicate type names and incomplete adapters throw instead of being silently overwritten.
+
+
+## Raw and interpreted input
+
+Input actions contain serializable raw input values. Before `checkInput` runs, the package interprets those values into their domain values. Its argument contains both forms:
+
+```ts
+checkInput: ({ rawInput, input, parameters, solution, metadata }) => {
+	// rawInput: values suitable for storage and transport
+	// input: interpreted numbers, quantities, expressions, and other domain values
+	return input.answer === solution?.answer
+}
+```
+
+Because every exercise defines different fields, interpreted input is initially typed as a record of unknown values. `getInput` retrieves one field, checks its runtime type, and returns the corresponding TypeScript type:
+
+```ts
+const count = getInput('count', data, 'number')
+const name = getInput('name', data, 'string')
+const quantity = getInput('quantity', data, Quantity)
+```
+
+Use `getInputs` when several fields share a type or need a matching list of types:
+
+```ts
+const [left, right] = getInputs(['left', 'right'], data, 'number')
+const [count, quantity] = getInputs(['count', 'quantity'], data, ['number', Quantity])
+```
+
+Both helpers throw when a field is missing or has an unexpected type. Interpretation itself is provided by [@step-wise/input-interpretation](https://www.npmjs.com/package/@step-wise/input-interpretation).
+
+
+## Defining a solution
+
+`getSolution` is optional. If it is absent, `data.solution` is `undefined`, and `checkInput` can compare the interpreted input directly with the parameters:
+
+```ts
+checkInput: ({ input, parameters }) => input.answer === parameters.left + parameters.right
+```
+
+Most exercises derive their complete solution directly from the parameters:
+
+```ts
+getSolution: parameters => ({
+	answer: parameters.left + parameters.right,
+})
+```
+
+The framework always calls `getSolution(parameters, inputDependency, staticSolution)`. Ordinary exercises can omit unused arguments. This keeps simple definitions short while giving input-dependent exercises access to the complete lifecycle.
+
+
+## Solutions that depend on earlier input
+
+Sometimes the appropriate solution depends on how the learner approached the problem. Such exercises can maintain an input dependency in their state:
+
+```ts
+updateInputDependency: ({ previousInputDependency, input }) =>
+	input.solveFor === undefined ? previousInputDependency : input.solveFor as 'left' | 'right',
+
+getStaticSolution: parameters => ({
+	total: parameters.left + parameters.right,
+}),
+
+getSolution: (parameters, solveFor, staticSolution) => {
+	if (solveFor === 'left') return { left: staticSolution.total! - parameters.right }
+	return { right: staticSolution.total! - parameters.left }
+},
+```
+
+The lifecycle consists of three optional callbacks. The input dependency initially is `undefined`:
+
+- `getStaticSolution(parameters)` calculates a reusable, input-independent partial solution.
+- `updateInputDependency({ parameters, previousInputDependency, staticSolution, input, step })` updates the dependency from the input submitted for the current step. The unsplit main problem uses step `0`.
+- `getSolution(parameters, inputDependency, staticSolution)` calculates the dynamic portion of the solution. The framework merges this over the static portion.
+
+All three callbacks may be synchronous or asynchronous. The runtime definition checks enforce these relationships:
+
+- `getStaticSolution` requires `updateInputDependency`.
+- `updateInputDependency` requires `getSolution`.
+
+If no updater exists, the resolution helper preserves the previous dependency. Returning `undefined` removes the dependency from state. If no static generator exists, the package supplies `{}` as the static solution. Static fields are automatically included in the final solution; dynamic fields with the same names override them. The builder stores dependencies through the exercise's generic serialization operation, so they may contain registered domain values while persisted exercise state remains plain data. Group mode stores a separate dependency for each participant. An input action may include `adoptUserHistory`, identifying the participant whose work it continues. The reducer then starts from that participant's previous input dependency and stores the updated dependency for the submitting participant. Accumulated input follows these references backward, so chained branches are reconstructed without copying earlier actions.
+
+The package exports focused helpers for consumers implementing the lifecycle:
+
+- `resolveUpdatedInputDependency(definition, data)`
+- `resolveStaticSolution(definition, parameters)`
+- `resolveSolution(definition, parameters, inputDependency, staticSolution)`
+
+
+## Looking up previous input
+
+The history helpers accept either solo or group exercise instances:
+
+- `getLastRawInput(instance, userId?, options?)` returns stored input values.
+- `getLastInput(exercise, instance, userId?, options?)` returns interpreted values using the exercise's value types.
+- `getAccumulatedRawInput(instance, userId?, options?)` combines partial input actions, with later values replacing earlier values for repeated fields.
+- `getAccumulatedInput(exercise, instance, userId?, options?)` provides the interpreted version of that combined input.
+- `getAccumulatedReport(instance, userId?, options?)` combines reports from the corresponding resolved input actions in the same way.
+- `hasPreviousInput(instance, userId?)` reports whether an input exists.
+- `getLastRawInputAtStep`, `getLastInputAtStep(exercise, instance, step, userId?, options?)`, and `hasPreviousInputAtStep` provide the corresponding operations for one step.
+
+For group histories, `userId` is required. By default, lookups may return input from a pending group event. Pass `{ resolvedOnly: true }` to ignore pending actions. The accumulated helpers also accept `throughEventIndex` to reconstruct input at an earlier point in the history:
+
+```ts
+const input = getAccumulatedInput(exercise, instance, userId, { resolvedOnly: true, throughEventIndex: 4 })
+```
+
+
+## TypeScript types
+
+The main author-facing types are:
+
+- `MonoExerciseSpec` and `MonoExercise` for single-stage exercises.
+- `StepExerciseSpec` and `StepExercise` for guided exercises.
+- `InputExerciseParameters`, `InputExerciseInput`, and `InputExerciseSolution` for exercise-specific data.
+- `CheckInputData` for the object supplied to `checkInput`, including the exercise-bound `areValuesEqual` operation.
+- `ValueTypes` for optional domain capabilities on an exercise specification, and `InputExerciseValueOperations` for the operations exposed by a built exercise.
+- `GetSolution`, `GetStaticSolution`, and `UpdateInputDependency` for solution generation.
+- `StepExerciseSteps`, `StepExerciseState`, and `StepExerciseMetadata` for step structures.
+- `InputExerciseAction` and `InputExerciseRawInput` for stored learner actions.
+
+Prefer supplying concrete parameter and solution types to the builders. This gives `generateParameters`, the solution callbacks, and `checkInput` a shared inferred contract.

package/dist/InputExercise/checkInput.d.ts

@@ -0,0 +1,8 @@
+import type { CheckInputResult, GroupInputExerciseReport, InputExerciseReport } from './types.ts';
+export declare function normalizeCheckInputResult(result: CheckInputResult): {
+    correct: boolean;
+    report?: InputExerciseReport;
+};
+export declare function getGroupInputExerciseReport(userIds: readonly (string | undefined)[], reports: readonly (InputExerciseReport | undefined)[]): GroupInputExerciseReport | undefined;
+export declare function mergeInputExerciseReports(previousReport: InputExerciseReport | undefined, report: InputExerciseReport | undefined): InputExerciseReport | undefined;
+//# sourceMappingURL=checkInput.d.ts.map

package/dist/InputExercise/checkInput.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkInput.d.ts","sourceRoot":"","sources":["../../src/InputExercise/checkInput.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,wBAAwB,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAA;AAEjG,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,gBAAgB,GAAG;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,mBAAmB,CAAA;CAAE,CAKtH;AAED,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,SAAS,CAAC,MAAM,GAAG,SAAS,CAAC,EAAE,EAAE,OAAO,EAAE,SAAS,CAAC,mBAAmB,GAAG,SAAS,CAAC,EAAE,GAAG,wBAAwB,GAAG,SAAS,CAQjL;AAED,wBAAgB,yBAAyB,CAAC,cAAc,EAAE,mBAAmB,GAAG,SAAS,EAAE,MAAM,EAAE,mBAAmB,GAAG,SAAS,GAAG,mBAAmB,GAAG,SAAS,CAGnK"}

package/dist/InputExercise/checkInput.js

@@ -0,0 +1,26 @@
+import { hasOnlyKeys, isBoolean, isPlainDataObject, isPlainObject } from '@step-wise/js-utils';
+export function normalizeCheckInputResult(result) {
+    if (isBoolean(result))
+        return { correct: result };
+    if (!isPlainObject(result) || !hasOnlyKeys(result, ['correct', 'report']) || !isBoolean(result.correct))
+        throw new TypeError(`Invalid checkInput result: expected a boolean or an object with a boolean "correct" property and an optional report.`);
+    if (result.report !== undefined && !isPlainDataObject(result.report))
+        throw new TypeError(`Invalid checkInput report: expected a plain data object.`);
+    return result;
+}
+export function getGroupInputExerciseReport(userIds, reports) {
+    const report = Object.fromEntries(reports.flatMap((userReport, index) => {
+        if (userReport === undefined)
+            return [];
+        const userId = userIds[index];
+        if (userId === undefined)
+            throw new TypeError(`A userId is required when creating a group exercise report.`);
+        return [[userId, userReport]];
+    }));
+    return Object.keys(report).length === 0 ? undefined : report;
+}
+export function mergeInputExerciseReports(previousReport, report) {
+    if (report === undefined)
+        return previousReport;
+    return { ...previousReport, ...report };
+}

package/dist/InputExercise/getInput.d.ts

@@ -0,0 +1,24 @@
+import type { CheckInputData } from './types.ts';
+type PrimitiveInputType = 'number' | 'string' | 'boolean';
+type PrimitiveInputTypeMap = {
+    number: number;
+    string: string;
+    boolean: boolean;
+};
+type InputConstructor = abstract new (...args: never[]) => unknown;
+type InputType = InputConstructor | PrimitiveInputType;
+type InputTypesForKeys<Keys extends readonly string[]> = {
+    readonly [Index in keyof Keys]: InputType;
+};
+type InputInstance<Type extends InputType> = Type extends PrimitiveInputType ? PrimitiveInputTypeMap[Type] : Type extends InputConstructor ? InstanceType<Type> : never;
+type InputInstances<Types extends readonly InputType[]> = {
+    [Index in keyof Types]: InputInstance<Types[Index]>;
+};
+export declare function getInput<Type extends PrimitiveInputType>(key: string, data: CheckInputData, inputType: Type): PrimitiveInputTypeMap[Type];
+export declare function getInput<Constructor extends InputConstructor>(key: string, data: CheckInputData, inputType: Constructor): InstanceType<Constructor>;
+export declare function getInputs<const Keys extends readonly string[], Type extends InputType>(keys: Keys, data: CheckInputData, inputType: Type): {
+    [Index in keyof Keys]: InputInstance<Type>;
+};
+export declare function getInputs<const Keys extends readonly string[], const Types extends InputTypesForKeys<Keys>>(keys: Keys, data: CheckInputData, inputTypes: Types): InputInstances<Types>;
+export {};
+//# sourceMappingURL=getInput.d.ts.map

package/dist/InputExercise/getInput.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"getInput.d.ts","sourceRoot":"","sources":["../../src/InputExercise/getInput.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAEhD,KAAK,kBAAkB,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAA;AACzD,KAAK,qBAAqB,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAAA;AAEjF,KAAK,gBAAgB,GAAG,QAAQ,MAAM,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,OAAO,CAAA;AAClE,KAAK,SAAS,GAAG,gBAAgB,GAAG,kBAAkB,CAAA;AAEtD,KAAK,iBAAiB,CAAC,IAAI,SAAS,SAAS,MAAM,EAAE,IAAI;IAAE,QAAQ,EAAE,KAAK,IAAI,MAAM,IAAI,GAAG,SAAS;CAAE,CAAA;AACtG,KAAK,aAAa,CAAC,IAAI,SAAS,SAAS,IAAI,IAAI,SAAS,kBAAkB,GAAG,qBAAqB,CAAC,IAAI,CAAC,GAAG,IAAI,SAAS,gBAAgB,GAAG,YAAY,CAAC,IAAI,CAAC,GAAG,KAAK,CAAA;AACvK,KAAK,cAAc,CAAC,KAAK,SAAS,SAAS,SAAS,EAAE,IAAI;KAAG,KAAK,IAAI,MAAM,KAAK,GAAG,aAAa,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;CAAE,CAAA;AAkBjH,wBAAgB,QAAQ,CAAC,IAAI,SAAS,kBAAkB,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,EAAE,SAAS,EAAE,IAAI,GAAG,qBAAqB,CAAC,IAAI,CAAC,CAAA;AAC1I,wBAAgB,QAAQ,CAAC,WAAW,SAAS,gBAAgB,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,EAAE,SAAS,EAAE,WAAW,GAAG,YAAY,CAAC,WAAW,CAAC,CAAA;AAMpJ,wBAAgB,SAAS,CAAC,KAAK,CAAC,IAAI,SAAS,SAAS,MAAM,EAAE,EAAE,IAAI,SAAS,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,cAAc,EAAE,SAAS,EAAE,IAAI,GAAG;KAAG,KAAK,IAAI,MAAM,IAAI,GAAG,aAAa,CAAC,IAAI,CAAC;CAAE,CAAA;AAC1L,wBAAgB,SAAS,CAAC,KAAK,CAAC,IAAI,SAAS,SAAS,MAAM,EAAE,EAAE,KAAK,CAAC,KAAK,SAAS,iBAAiB,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,cAAc,EAAE,UAAU,EAAE,KAAK,GAAG,cAAc,CAAC,KAAK,CAAC,CAAA"}

package/dist/InputExercise/getInput.js

@@ -0,0 +1,23 @@
+function isInputConstructor(inputType) {
+    return typeof inputType === 'function';
+}
+function isInputTypeArray(inputTypes) {
+    return Array.isArray(inputTypes);
+}
+function getInputValue(key, data, inputType) {
+    const input = data.input[key];
+    const matches = isInputConstructor(inputType) ? input instanceof inputType : typeof input === inputType;
+    if (!matches)
+        throw new TypeError(`Invalid getInput call: input "${key}" has an unexpected type.`);
+    return input;
+}
+export function getInput(key, data, inputType) {
+    return getInputValue(key, data, inputType);
+}
+export function getInputs(keys, data, inputTypes) {
+    if (!isInputTypeArray(inputTypes))
+        return keys.map(key => getInputValue(key, data, inputTypes));
+    if (keys.length !== inputTypes.length)
+        throw new RangeError(`Invalid getInputs call: received ${keys.length} keys and ${inputTypes.length} input types.`);
+    return keys.map((key, index) => getInputValue(key, data, inputTypes[index]));
+}

package/dist/InputExercise/guards.d.ts

@@ -0,0 +1,4 @@
+export declare function hasInputExerciseProperties(value: unknown): value is Record<string, unknown> & {
+    metadata: Record<string, unknown>;
+};
+//# sourceMappingURL=guards.d.ts.map

package/dist/InputExercise/guards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guards.d.ts","sourceRoot":"","sources":["../../src/InputExercise/guards.ts"],"names":[],"mappings":"AAMA,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,CAUnI"}

package/dist/InputExercise/guards.js

@@ -0,0 +1,30 @@
+import { isPlainObject } from '@step-wise/js-utils';
+import { isExercise } from '@step-wise/exercise-definition';
+// Check if an exercise has the properties expected of an input exercise.
+export function hasInputExerciseProperties(value) {
+    if (!isPlainObject(value) || !isExercise(value))
+        return false;
+    if (!isInputExerciseValueOperations(value.valueOperations))
+        return false;
+    if (typeof value.checkInput !== 'function' || typeof value.processSoloAction !== 'function' || typeof value.processGroupActions !== 'function')
+        return false;
+    if (value.updateInputDependency !== undefined && typeof value.updateInputDependency !== 'function')
+        return false;
+    if (value.getStaticSolution !== undefined && typeof value.getStaticSolution !== 'function')
+        return false;
+    if (value.getSolution !== undefined && typeof value.getSolution !== 'function')
+        return false;
+    if (value.getStaticSolution !== undefined && value.updateInputDependency === undefined)
+        return false;
+    if (value.updateInputDependency !== undefined && value.getSolution === undefined)
+        return false;
+    return true;
+}
+function isInputExerciseValueOperations(value) {
+    return isPlainObject(value)
+        && typeof value.serialize === 'function'
+        && typeof value.deserialize === 'function'
+        && typeof value.interpretInput === 'function'
+        && typeof value.toInputValue === 'function'
+        && typeof value.areValuesEqual === 'function';
+}

package/dist/InputExercise/history.d.ts

@@ -0,0 +1,22 @@
+import { type BaseExerciseInstanceByMode, type ExerciseMode, type ExerciseState } from '@step-wise/exercise-definition';
+import type { GroupInputExerciseReport, InputExerciseAction, InputExerciseInput, InputExerciseRawInput, InputExerciseReport, InputExerciseValueOperations, SoloInputExerciseReport } from './types.ts';
+export type InputExerciseHistoryData<TState extends ExerciseState = ExerciseState> = {
+    [Mode in ExerciseMode]: Pick<BaseExerciseInstanceByMode<InputExerciseAction, TState, Record<string, never>, Mode extends 'solo' ? SoloInputExerciseReport : GroupInputExerciseReport>[Mode], 'mode' | 'initialState' | 'history'>;
+}[ExerciseMode];
+export type LastInputOptions = {
+    resolvedOnly?: boolean;
+};
+export type AccumulatedInputOptions = LastInputOptions & {
+    throughEventIndex?: number;
+};
+export declare function getLastRawInput(instance: InputExerciseHistoryData, userId?: string, options?: LastInputOptions): InputExerciseRawInput | undefined;
+export declare function getAccumulatedRawInput(instance: InputExerciseHistoryData, userId?: string, options?: AccumulatedInputOptions): InputExerciseRawInput | undefined;
+export declare function getAccumulatedReport(instance: InputExerciseHistoryData, userId?: string, options?: Pick<AccumulatedInputOptions, 'throughEventIndex'>): InputExerciseReport | undefined;
+export declare function getAccumulatedInput(exercise: {
+    valueOperations: InputExerciseValueOperations;
+}, instance: InputExerciseHistoryData, userId?: string, options?: AccumulatedInputOptions): InputExerciseInput | undefined;
+export declare function getLastInput(exercise: {
+    valueOperations: InputExerciseValueOperations;
+}, instance: InputExerciseHistoryData, userId?: string, options?: LastInputOptions): InputExerciseInput | undefined;
+export declare function hasPreviousInput(instance: InputExerciseHistoryData, userId?: string): boolean;
+//# sourceMappingURL=history.d.ts.map

package/dist/InputExercise/history.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"history.d.ts","sourceRoot":"","sources":["../../src/InputExercise/history.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,0BAA0B,EAAE,KAAK,YAAY,EAAE,KAAK,aAAa,EAAgC,MAAM,gCAAgC,CAAA;AAErJ,OAAO,KAAK,EAAE,wBAAwB,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,4BAA4B,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAA;AAGtM,MAAM,MAAM,wBAAwB,CAAC,MAAM,SAAS,aAAa,GAAG,aAAa,IAAI;KACnF,IAAI,IAAI,YAAY,GAAG,IAAI,CAAC,0BAA0B,CACtD,mBAAmB,EACnB,MAAM,EACN,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,EACrB,IAAI,SAAS,MAAM,GAAG,uBAAuB,GAAG,wBAAwB,CACxE,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAAC;CAC7C,CAAC,YAAY,CAAC,CAAA;AAEf,MAAM,MAAM,gBAAgB,GAAG;IAC9B,YAAY,CAAC,EAAE,OAAO,CAAA;CACtB,CAAA;AAED,MAAM,MAAM,uBAAuB,GAAG,gBAAgB,GAAG;IACxD,iBAAiB,CAAC,EAAE,MAAM,CAAA;CAC1B,CAAA;AAGD,wBAAgB,eAAe,CAAC,QAAQ,EAAE,wBAAwB,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,OAAO,GAAE,gBAAqB,GAAG,qBAAqB,GAAG,SAAS,CAyBtJ;AAGD,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,wBAAwB,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,OAAO,GAAE,uBAA4B,GAAG,qBAAqB,GAAG,SAAS,CA0CpK;AAGD,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,wBAAwB,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,OAAO,GAAE,IAAI,CAAC,uBAAuB,EAAE,mBAAmB,CAAM,GAAG,mBAAmB,GAAG,SAAS,CA2C3L;AAGD,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE;IAAE,eAAe,EAAE,4BAA4B,CAAA;CAAE,EAAE,QAAQ,EAAE,wBAAwB,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,OAAO,GAAE,uBAA4B,GAAG,kBAAkB,GAAG,SAAS,CAG3N;AAGD,wBAAgB,YAAY,CAAC,QAAQ,EAAE;IAAE,eAAe,EAAE,4BAA4B,CAAA;CAAE,EAAE,QAAQ,EAAE,wBAAwB,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,OAAO,GAAE,gBAAqB,GAAG,kBAAkB,GAAG,SAAS,CAG7M;AAGD,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,wBAAwB,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAE7F"}

package/dist/InputExercise/history.js

@@ -0,0 +1,135 @@
+import { throwUnsupportedExerciseMode } from '@step-wise/exercise-definition';
+// Get the last given raw input from the user. For group exercises, this may be an unresolved action input unless resolvedOnly is true.
+export function getLastRawInput(instance, userId, options = {}) {
+    const { mode } = instance;
+    const { resolvedOnly = false } = options;
+    switch (mode) {
+        case 'solo':
+            for (let index = instance.history.length - 1; index >= 0; index--) {
+                const action = instance.history[index].action;
+                if (action.type === 'input')
+                    return action.input;
+            }
+            return undefined;
+        case 'group': {
+            if (userId === undefined)
+                throw new TypeError(`A userId is required when retrieving input from a group exercise history.`);
+            let historyUserId = userId;
+            for (let index = instance.history.length - 1; index >= 0; index--) {
+                const event = instance.history[index];
+                const action = event.actions.find(userAction => userAction.userId === historyUserId)?.action;
+                if (action?.type !== 'input')
+                    continue;
+                if (!resolvedOnly || 'state' in event)
+                    return action.input;
+                historyUserId = action.adoptUserHistory ?? historyUserId;
+            }
+            return undefined;
+        }
+        default:
+            return throwUnsupportedExerciseMode(mode);
+    }
+}
+// Combine a user's input actions through the requested history event. Later values overwrite earlier values with the same field ID.
+export function getAccumulatedRawInput(instance, userId, options = {}) {
+    const { mode } = instance;
+    const { resolvedOnly = false, throughEventIndex = instance.history.length - 1 } = options;
+    const lastIndex = Math.min(throughEventIndex, instance.history.length - 1);
+    // Set up accumulators.
+    const input = {};
+    let hasInput = false;
+    const addInput = (action) => {
+        if (action?.type !== 'input')
+            return;
+        Object.assign(input, action.input);
+        hasInput = true;
+    };
+    // Depending on the mode, walk through the actions and add respective inputs.
+    switch (mode) {
+        case 'solo':
+            for (let index = 0; index <= lastIndex; index++)
+                addInput(instance.history[index].action);
+            break;
+        case 'group':
+            if (userId === undefined)
+                throw new TypeError(`A userId is required when retrieving input from a group exercise history.`);
+            let historyUserId = userId;
+            for (let index = lastIndex; index >= 0; index--) {
+                const event = instance.history[index];
+                const action = event.actions.find(userAction => userAction.userId === historyUserId)?.action;
+                if (action?.type !== 'input')
+                    continue;
+                if (!resolvedOnly || 'state' in event) {
+                    Object.entries(action.input).forEach(([id, value]) => {
+                        if (!(id in input))
+                            input[id] = value;
+                    });
+                    hasInput = true;
+                }
+                historyUserId = action.adoptUserHistory ?? historyUserId;
+            }
+            break;
+        default:
+            return throwUnsupportedExerciseMode(mode);
+    }
+    return hasInput ? input : undefined;
+}
+// Combine reports belonging to a user's resolved input actions. Later values overwrite earlier values with the same key.
+export function getAccumulatedReport(instance, userId, options = {}) {
+    const { mode } = instance;
+    const { throughEventIndex = instance.history.length - 1 } = options;
+    const lastIndex = Math.min(throughEventIndex, instance.history.length - 1);
+    const report = {};
+    let hasReport = false;
+    switch (mode) {
+        case 'solo':
+            for (let index = 0; index <= lastIndex; index++) {
+                const event = instance.history[index];
+                if (event.action.type !== 'input' || event.report === undefined)
+                    continue;
+                Object.assign(report, event.report);
+                hasReport = true;
+            }
+            break;
+        case 'group': {
+            if (userId === undefined)
+                throw new TypeError(`A userId is required when retrieving a report from a group exercise history.`);
+            let historyUserId = userId;
+            for (let index = lastIndex; index >= 0; index--) {
+                const event = instance.history[index];
+                const action = event.actions.find(userAction => userAction.userId === historyUserId)?.action;
+                if (action?.type !== 'input')
+                    continue;
+                if ('state' in event) {
+                    const eventReport = event.report?.[historyUserId];
+                    if (eventReport !== undefined) {
+                        Object.entries(eventReport).forEach(([key, value]) => {
+                            if (!(key in report))
+                                report[key] = value;
+                        });
+                        hasReport = true;
+                    }
+                }
+                historyUserId = action.adoptUserHistory ?? historyUserId;
+            }
+            break;
+        }
+        default:
+            return throwUnsupportedExerciseMode(mode);
+    }
+    return hasReport ? report : undefined;
+}
+// Combine and interpret a user's input actions through the requested history event.
+export function getAccumulatedInput(exercise, instance, userId, options = {}) {
+    const rawInput = getAccumulatedRawInput(instance, userId, options);
+    return rawInput === undefined ? undefined : exercise.valueOperations.interpretInput(rawInput);
+}
+// Get the last given input from the user and interpret all its values.
+export function getLastInput(exercise, instance, userId, options = {}) {
+    const rawInput = getLastRawInput(instance, userId, options);
+    return rawInput === undefined ? undefined : exercise.valueOperations.interpretInput(rawInput);
+}
+// Check if a user has made a previous input at the given step.
+export function hasPreviousInput(instance, userId) {
+    return getLastRawInput(instance, userId) !== undefined;
+}

package/dist/InputExercise/index.d.ts

@@ -0,0 +1,6 @@
+export * from './types.ts';
+export { type GroupInputExerciseAttemptState, type GroupInputExerciseDependencyState, type InputExerciseAttemptState, type InputExerciseDependencyState, type InputExerciseReducerInput, type SoloInputExerciseAttemptState, type SoloInputExerciseDependencyState, getInputDependency } from './reducerSupport.ts';
+export * from './getInput.ts';
+export * from './history.ts';
+export * from './solutions.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/InputExercise/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/InputExercise/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAA;AAC1B,OAAO,EAAE,KAAK,8BAA8B,EAAE,KAAK,iCAAiC,EAAE,KAAK,yBAAyB,EAAE,KAAK,4BAA4B,EAAE,KAAK,yBAAyB,EAAE,KAAK,6BAA6B,EAAE,KAAK,gCAAgC,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAA;AACnT,cAAc,eAAe,CAAA;AAC7B,cAAc,cAAc,CAAA;AAC5B,cAAc,gBAAgB,CAAA"}

package/dist/InputExercise/index.js

@@ -0,0 +1,5 @@
+export * from './types.js';
+export { getInputDependency } from './reducerSupport.js';
+export * from './getInput.js';
+export * from './history.js';
+export * from './solutions.js';

package/dist/InputExercise/parameterSerialization.d.ts

@@ -0,0 +1,5 @@
+import { type PlainDataObject } from '@step-wise/js-utils';
+import type { InputExerciseParameters, InputExerciseValueOperations } from './types.ts';
+export declare function serializeInputExerciseParameters(parameters: InputExerciseParameters, serialize: InputExerciseValueOperations['serialize']): PlainDataObject;
+export declare function deserializeInputExerciseParameters<TParameters extends InputExerciseParameters>(parameters: PlainDataObject, deserialize: InputExerciseValueOperations['deserialize']): TParameters;
+//# sourceMappingURL=parameterSerialization.d.ts.map

package/dist/InputExercise/parameterSerialization.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parameterSerialization.d.ts","sourceRoot":"","sources":["../../src/InputExercise/parameterSerialization.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,eAAe,EAAqB,MAAM,qBAAqB,CAAA;AAE7E,OAAO,KAAK,EAAE,uBAAuB,EAAE,4BAA4B,EAAE,MAAM,YAAY,CAAA;AAGvF,wBAAgB,gCAAgC,CAAC,UAAU,EAAE,uBAAuB,EAAE,SAAS,EAAE,4BAA4B,CAAC,WAAW,CAAC,GAAG,eAAe,CAI3J;AAGD,wBAAgB,kCAAkC,CAAC,WAAW,SAAS,uBAAuB,EAAE,UAAU,EAAE,eAAe,EAAE,WAAW,EAAE,4BAA4B,CAAC,aAAa,CAAC,GAAG,WAAW,CAIlM"}

package/dist/InputExercise/parameterSerialization.js

@@ -0,0 +1,15 @@
+import { isPlainDataObject } from '@step-wise/js-utils';
+// Serialize runtime parameters and ensure that the result is suitable for storage.
+export function serializeInputExerciseParameters(parameters, serialize) {
+    const serializedParameters = serialize(parameters);
+    if (!isPlainDataObject(serializedParameters))
+        throw new TypeError('Invalid generated input-exercise parameters: serialization must result in a plain data object.');
+    return serializedParameters;
+}
+// Restore stored parameters before passing them to author-facing input-exercise logic.
+export function deserializeInputExerciseParameters(parameters, deserialize) {
+    const deserializedParameters = deserialize(parameters);
+    if (typeof deserializedParameters !== 'object' || deserializedParameters === null || Array.isArray(deserializedParameters))
+        throw new TypeError('Invalid stored input-exercise parameters: deserialization must result in an object.');
+    return deserializedParameters;
+}