@intellectif/lk-core 1.1.0 → 1.3.0

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # @intellectif/lk-core
 
+## 1.3.0
+
+### Minor Changes
+
+- [#90](https://github.com/intellectif/learning-kit/pull/90) [`9b5f5ef`](https://github.com/intellectif/learning-kit/commit/9b5f5ef6243f825c1336628d38816789993455b3) Thanks [@diego28e](https://github.com/diego28e)! - **Smaller bundles, one list of built-in types, and two deprecations**: importing one function from lk-core no longer bundles all of zod.
+
+  **Action required:** none. Two things are deprecated and keep working throughout 1.x: a fill-in-the-blanks blank's `caseSensitive` / `trimWhitespace` (write `match: { caseSensitive, trim }`), and `seededShuffle` without a `version` (write `{ version: 1 }` to keep an order already recorded).
+
+  - **Smaller bundles.** An app that imports only `score`, or only `xAPIBuilder` from `/xapi`, used to bundle every one of zod's 60-odd locales: about 121 kB gzipped for `{ score }`. It is now about 54 kB. Grades, validation results and error messages are unchanged — every grade vector and validation expectation replays identically — and new size budgets hold lk-core to it.
+  - **`BUILT_IN_ACTIVITY_TYPES`, `BuiltInActivityType` and `isBuiltInActivityType`** name the types the SDK ships. `ActivityType` cannot, since a host's module augmentation widens it: use these to tell your own registered types from the SDK's.
+  - **`hintRevealsAnswer` withholds a hint it cannot check.** Given facts of a kind it cannot read, it now answers `true` — the hint reveals — where it answered `false` and let the hint through. No built-in type reaches that case today; a new one would have.
+  - **The built-in types are registered however your bundler splits lk-core.** They were registered as a module loaded, which held only because the build put that module beside the lookups; lk-core declares `sideEffects: false`, so a bundler may drop such a module. The registry is now created holding them.
+  - **Deprecated, still working throughout 1.x:** a blank's `caseSensitive` and `trimWhitespace` (`match.caseSensitive` and `match.trim` mean the same), and calling `seededShuffle` without `version` — it still draws version 1, but a 2.0 may make version 2 the default. See [Stability](https://github.com/intellectif/learning-kit/blob/main/docs/stability.md#deprecation).
+  - **Built with tsdown**, as tsup is no longer maintained. Every entry point exports the same names in ESM and CommonJS, the declarations describe the same API, and the grade and validation corpora replay identically; only the names of the internal chunk files differ.
+
+## 1.2.0
+
+### Minor Changes
+
+- [#88](https://github.com/intellectif/learning-kit/pull/88) [`493dd06`](https://github.com/intellectif/learning-kit/commit/493dd0648a73c7f47d889683bc9f7f08d8a0acc9) Thanks [@diego28e](https://github.com/diego28e)! - **Assistants for authors**: an item critic, a model's review of an item, and drafts from a passage, a transcript or a video's captions.
+
+  **Action required:** none unless your code switches over `AiRefusal` without a `default` branch (new member `'contradicts-item'`) or reads `AiCheckCase.request` without narrowing on `feature` (new `'item-critique'` and `'draft-generation'` cases). Nothing runs until you call it, no grade changes, and there is no lk-react release: lk-react 23.1 works with it as it is. See https://github.com/intellectif/learning-kit/blob/main/docs/upgrading.md
+
+  - **The item critic:** `critiqueDraft(type, draft)`, `critiqueDrafts(entries)` for a question set and `critiqueItemGroupDraft(group)` for a testlet point out what a reviewer would on an item that may be perfectly valid — a title, hint or passage that prints the answer, two options that read the same, the right option much longer than the rest, "all of the above" under shuffle, a word bank with no distractor, a text too long for its recording time, every right option in one position. Findings are `warning` or `advice`, in `DraftIssue`'s shape so an editor lists both, and never change what `validateDraft` says. Seventeen codes, documented with their rules: https://github.com/intellectif/learning-kit/blob/main/docs/authoring.md
+  - **A registered type** joins the critic through a new optional `authoring.critique`.
+  - **A model's review:** `aiCritiqueRequest` gives a model the item, every text field it may point at, and the critic's own findings; `checkAiCritique` lists its findings as `advice`, and refuses the whole reply as `contradicts-item` when a finding points at a field the item does not have or quotes words that field does not hold.
+  - **Drafts from a source:** `aiDraftsRequest` takes the types an author ticks — multiple choice, fill in the blanks, gap select, dictation, read-aloud, written response — in the author's order, an optional count (left out, as many as the source is worth, up to 50), the author's own instructions and your settings per type, and gives the model the JSON Schema of a reply: each type's own fields, no ids, HTML, media, switches or scoring settings; `checkAiDrafts` makes drafts with your ids and settings, in the author's order, each checked by `validateDraft` and the critic — from captions placed where its caption ends, a dictation with the stretch of video that says it; `aiDraftsRepairRequest` sends back what is unfinished, wrong or warned about; `generateDrafts` runs that loop, once by default and three times at most, and never throws for a model's failure. A draft is never approved by the SDK. https://github.com/intellectif/learning-kit/blob/main/docs/ai.md
+  - **A video's quizzes:** `interactiveVideoFromDrafts` makes the drafts an interactive video — each question where its caption ends, questions at one moment in the author's order, and every question without a moment in one quiz at the end of the video (`durationSeconds`).
+  - **ai-check:** a `critique` port runs four review cases and a `drafts` port six drafting cases, two of them video quizzes.
+
 ## 1.1.0
 
 ### Minor Changes

package/README.md

@@ -19,6 +19,7 @@ npm install @intellectif/lk-core
 - **`validateActivity(type, data)`** — the authoritative runtime validator. Returns a typed `{ success, data }` or a structured `{ success: false, errors[] }`, and **throws `UnknownActivityTypeError` if `type` is not registered** — so guard it when validating a content bank that may carry types this build does not know. `validateItemGroup(data)` is the equivalent for a `Stimulus` + `ItemGroup` container, which `validateActivity` cannot take.
 - **`validateDraft(type, draft)`** — for editors. Reports `complete`, `incomplete` (something not written yet) or `invalid` (something wrong), each issue with a `severity` and a `code` — documented for every problem the checks recognise — and deliberately no `success` boolean to misread. Stricter than `validateActivity`, never looser. **`createDraft(type, { newId })`** returns an empty draft to start from; a multiple-choice draft marks no option correct.
 - **An open type system** — `defineActivityType` / `registerActivityType` make an activity type a *value*, not a hard-coded union member: register one and `validateActivity`, `validateDraft`, `score`, `evaluate`, `redact` and `jsonSchemaFor` all work for it, with no SDK release. An `authoring` block on the descriptor gives it draft support.
+- **An item critic** — `critiqueDraft(type, draft)` (and `critiqueDrafts` for a question set, `critiqueItemGroupDraft` for a testlet) points out what a reviewer would on an item that may be perfectly valid: the right option much longer than the rest, an answer printed in the passage, a hint that gives it away, "all of the above" under shuffle. A finding is `warning` or `advice`, in `DraftIssue`'s shape, and never refuses an item.
 - **JSON Schema (Draft-7) export** — `jsonSchemaFor(type)` for any registered type (plus the static per-type exports), suitable for form generators or AI prompting.
 - **Scoring engine** — `score(activityType, data, response)` returning `{ score ∈ [0,1], maxScore: 1, passed, feedback, details }`. Pure, deterministic, 100 % test coverage enforced. It **throws** rather than inventing a number: `DeferredScoringError` for a deferred-graded type (`written-response`), and `RedactedScoringError` when handed a `redact()` projection, which has no answer key. Both are on the documented exam path — use `evaluate()` there, which returns `deferred` / `unscorable` instead of throwing.
 - **Dictation marking as data** — a dictation is graded by the character-level similarity of the typed text to the transcript, with one `ScoringDetail` per word carrying its own `score`. `alignDictation(data, text)` returns the same comparison the grade was made of (normalised strings, word pairings, which accepted transcript won), `diffDictationChars(reference, attempt)` the character-level edits for a marked display, and `dictationReferenceWords(data)` the ids and words a stored result can be checked against — so a review screen or an analytics job never re-implements the arithmetic. `score()` and `evaluate()` take an optional `{ rounding }` to compare the pass line as displayed.
@@ -28,7 +29,7 @@ npm install @intellectif/lk-core
 - **Item groups** — `Stimulus` + `ItemGroup` (one passage or recording serving several questions), `flattenSequence()` for seeded, shuffle-atomic presentation order with stable slot identity. Slot ids are positional by default (`"3"`, `"1.0"`); author a `slotKey` on an entry and its id survives an insert, so a stored response cannot slide onto a different question.
 - **Delivery policies** — `DeliveryPolicy` says what a school lets a learner see around a question: feedback, solutions, hints and AI help. `resolveDeliveryPolicy` spells one out (an unreadable setting restricts, never allows), `validateDeliveryPolicy` checks one before it is stored, and `combineDeliveryPolicies` keeps a setting on only where every policy leaves it on.
 - **Scoring policies** — `ItemScoringPolicy` says how a paper's questions are scored when a learner can try again or ask for hints: `retries`, which try `counts`, and what a try and a hint cost. `scoreTries` does the arithmetic, `evaluate(…, { scoring })` and `evaluateTries` reach a question's outcome from its answers, and `validateItemScoringPolicy` / `resolveItemScoringPolicy` refuse a policy that cannot be applied rather than guess — every setting moves a grade. No policy changes nothing, and the arithmetic is pinned by the grade vectors.
-- **AI help contracts** — the SDK calls no model; it builds what yours is given and checks what comes back. `aiExplanationRequest`, `aiHintRequest`, `aiWritingFeedbackRequest` and `aiCoachingRequest` build the requests a component makes, so a server can rebuild them from its own copy of an item; `checkAiExplanation`, `checkAiHint`, `checkAiWritingFeedback` and `checkAiCoaching` refuse an explanation that contradicts the grade, a hint that contains the answer, writing feedback that corrects words the learner never wrote, and coaching on a reading that names a word the speech engine did not mark or a sound it did not report; `checkAiWritingFeedback` computes the rubric's indicative score itself.
+- **AI help contracts** — the SDK calls no model; it builds what yours is given and checks what comes back. `aiExplanationRequest`, `aiHintRequest`, `aiWritingFeedbackRequest` and `aiCoachingRequest` build the requests a component makes, so a server can rebuild them from its own copy of an item; `checkAiExplanation`, `checkAiHint`, `checkAiWritingFeedback` and `checkAiCoaching` refuse an explanation that contradicts the grade, a hint that contains the answer, writing feedback that corrects words the learner never wrote, and coaching on a reading that names a word the speech engine did not mark or a sound it did not report; `checkAiWritingFeedback` computes the rubric's indicative score itself. For authors, `aiCritiqueRequest` / `checkAiCritique` give a model's review of an item, whose every finding must point at the item's own fields, and `aiDraftsRequest` / `checkAiDrafts` / `generateDrafts` draft the types an author ticks, in the author's order, from a passage, a script or captions — each checked by `validateDraft`, critiqued, repaired in a bounded loop, and never approved by the SDK — and `interactiveVideoFromDrafts` makes them a video's quizzes, each question where its caption ends or at the end.
 - **Attempt plans** — `planAttempt(entries, { seed, shuffleEntries, points, delivery })` freezes the exact paper a learner sat, and the delivery policy it was sat under: slot order, per-slot points, a content hash of each item, and a `planHash` over the lot. `verifyAttemptPlan(plan, current)` reports the drift when that content is later edited (`changedSlotIds`, `changedStimulusSlotIds`, `changedPointsSlotIds`, `missingSlotIds`, …) — the thing you need during a remark or an appeal. `scoredItemsFromPlan(plan, outcomes)` turns collected outcomes into the `ScoredItem[]` composition wants, and defaults a slot with **no** outcome to `deferred` rather than silently shrinking the denominator.
 - **Attempt state** — `serializeAttemptState(plan, progress)` / `restoreAttemptState(plan, snapshot)` round-trip an interrupted attempt (responses, submitted slots, position) and are **bound to the plan**: restoring answers onto a paper the learner never sat throws instead of succeeding quietly. `diffResponses(before, after)` reports what moved between two snapshots, including an answer the learner *cleared*.
 - **Media playback policy** — `media.playback` on an audio recording: `maxPlays`, `seek`, `rate`, and advisory `nativeControlHints`. `resolvePlaybackPolicy()` derives the defaults once so the schema, the plan and the renderer cannot drift. Budgets are frozen into the plan by `planAttempt`, so editing `maxPlays` mid-window cannot change what a past learner was held to, and `planAttempt` refuses a paper where one recording is budgeted under two keys.
@@ -132,7 +133,7 @@ Zod is the single runtime dependency, pinned to one exact version and private: n
 - **What is supported, and since when** — [Features](https://github.com/intellectif/learning-kit/blob/main/docs/features.md): every activity and capability, the `lk-core` / `lk-react` versions it arrived in, and its guide.
 - **What changed** — [GitHub Releases](https://github.com/intellectif/learning-kit/releases), one per package version, and the same notes in each package's `CHANGELOG.md` (it ships in the npm package, so it is in your `node_modules` too). Notes written since release notes gained a template — every release after lk-core 0.20.0 / lk-react 20.0.0 — start with a one-line summary and **Action required**: `none`, or what to do. Earlier notes lead with the detail; the version map in the upgrading guide says what each one asks of you.
 - **How to upgrade** — [Upgrading](https://github.com/intellectif/learning-kit/blob/main/docs/upgrading.md): which `lk-core` goes with which `lk-react`, and a section per release saying what, if anything, you need to change. A `lk-react` major is often only the `lk-core` peer bump; the map says so.
-- **Hearing about a release** — on GitHub, **Watch → Custom → Releases**, or subscribe to [the releases feed](https://github.com/intellectif/learning-kit/releases.atom). Better still, let your dependency bot bring each release to you as a pull request, with its notes — and keep the two packages together in one, since they move together:
+- **Hearing about a release** — on GitHub, **Watch → Custom → Releases**, or subscribe to [the releases feed](https://github.com/intellectif/learning-kit/releases.atom). Better still, let your dependency bot bring each release to you as a pull request, with its notes — and keep the two packages together in one, since a `lk-react` release names the `lk-core` it needs:
 
   ```yaml
   # .github/dependabot.yml — one entry per directory with a package.json
@@ -148,7 +149,7 @@ Zod is the single runtime dependency, pinned to one exact version and private: n
 
   With Renovate: `"packageRules": [{ "matchPackageNames": ["@intellectif/lk-core", "@intellectif/lk-react"], "groupName": "learning-kit" }]`.
 
-  `lk-core` is still `0.x`, and a caret range on a `0.x` version matches only that minor: `^0.18.0` never installs `0.19.0`. A bot is how you find out there is one.
+  A caret range installs every later minor and patch of its major — `^1.2.0` takes `1.3.0` — and never a new major. A bot is how you hear about either, with its notes.
 
 ## Documentation