@intellectif/lk-react 6.0.0 → 6.1.0

package/dist/hooks/useXAPI.d.ts

@@ -10,6 +10,37 @@ interface UseXAPIResult {
      */
     sendStatement: (statement: XAPIStatement) => Promise<void>;
 }
+/**
+ * Delivers xAPI statements to a Learning Record Store, fire-and-forget.
+ *
+ * Telemetry must never break the learner's attempt, so
+ * {@link UseXAPIResult.sendStatement} **never rejects**: network errors and 5xx
+ * responses are retried (backoff 1s / 2s / 4s, up to 3 retries), a 4xx fails
+ * immediately, and any final failure is reported to `config.onError` instead of
+ * throwing. See `XAPIConfig` in `@intellectif/lk-core` for the options.
+ *
+ * The hook is also where learner identity is applied. Activity components
+ * cannot know who the learner is, so they emit an anonymous placeholder actor
+ * and a `urn:learning-kit:activity:*` object id; this hook substitutes
+ * `config.actor` and `config.activityId` on the way out — and only while those
+ * placeholders are still in place, so a statement you rewrote yourself is left
+ * alone.
+ *
+ * `sendStatement` keeps a stable identity across renders even when `config` is
+ * an inline object, so it is safe in a dependency array.
+ *
+ * ```tsx
+ * const { sendStatement } = useXAPI({
+ *   endpoint: 'https://your-lrs.example/xapi/statements',
+ *   auth: { type: 'bearer', token: 'YOUR_TOKEN' },
+ *   activityId: 'https://your-app.example/quiz/capital-jp',
+ *   actor: { objectType: 'Agent', mbox: 'mailto:learner@example.com' },
+ *   onError: (e) => console.error('xAPI send failed', e),
+ * });
+ *
+ * <MultipleChoice data={quiz} onComplete={(r) => void sendStatement(r.xapiStatement)} />
+ * ```
+ */
 declare function useXAPI(config: XAPIConfig): UseXAPIResult;
 
 export { type UseXAPIResult, useXAPI };

package/dist/hooks/useXAPI.js

@@ -1,3 +1,4 @@
-export { useXAPI } from '../chunk-E4MNA2IQ.js';
+'use client';
+export { useXAPI } from '../chunk-2TW6WLBC.js';
 //# sourceMappingURL=useXAPI.js.map
 //# sourceMappingURL=useXAPI.js.map

package/dist/index.cjs

@@ -1,15 +1,16 @@
+'use client';
 'use strict';
 
-var chunkCPF2JJG6_cjs = require('./chunk-CPF2JJG6.cjs');
-var chunkPBVMEOWI_cjs = require('./chunk-PBVMEOWI.cjs');
-var chunkYXG3UJVG_cjs = require('./chunk-YXG3UJVG.cjs');
+var chunkAMGK7DDM_cjs = require('./chunk-AMGK7DDM.cjs');
+var chunkDUIWK272_cjs = require('./chunk-DUIWK272.cjs');
+var chunkBE7R2X3S_cjs = require('./chunk-BE7R2X3S.cjs');
 var chunkNPY2F7F6_cjs = require('./chunk-NPY2F7F6.cjs');
-var chunkR3OZ6JHQ_cjs = require('./chunk-R3OZ6JHQ.cjs');
+var chunkMDYKYDRN_cjs = require('./chunk-MDYKYDRN.cjs');
 require('./chunk-PGEG7UZJ.cjs');
 var chunkNEWGUDA5_cjs = require('./chunk-NEWGUDA5.cjs');
 require('./chunk-4HZ7LQIH.cjs');
 var chunkXOR4MPEN_cjs = require('./chunk-XOR4MPEN.cjs');
-var chunkIYLQSNLE_cjs = require('./chunk-IYLQSNLE.cjs');
+var chunkPNNUPUH4_cjs = require('./chunk-PNNUPUH4.cjs');
 
 // src/components/types.ts
 function asRenderable(redacted) {
@@ -21,27 +22,31 @@ function asRenderableSequence(entries) {
 
 Object.defineProperty(exports, "ThemeProvider", {
   enumerable: true,
-  get: function () { return chunkCPF2JJG6_cjs.ThemeProvider; }
+  get: function () { return chunkAMGK7DDM_cjs.ThemeProvider; }
+});
+Object.defineProperty(exports, "createTailwindTheme", {
+  enumerable: true,
+  get: function () { return chunkAMGK7DDM_cjs.createTailwindTheme; }
 });
 Object.defineProperty(exports, "darkTheme", {
   enumerable: true,
-  get: function () { return chunkCPF2JJG6_cjs.darkTheme; }
+  get: function () { return chunkAMGK7DDM_cjs.darkTheme; }
 });
 Object.defineProperty(exports, "defaultTheme", {
   enumerable: true,
-  get: function () { return chunkCPF2JJG6_cjs.defaultTheme; }
+  get: function () { return chunkAMGK7DDM_cjs.defaultTheme; }
 });
 Object.defineProperty(exports, "useTheme", {
   enumerable: true,
-  get: function () { return chunkCPF2JJG6_cjs.useTheme; }
+  get: function () { return chunkAMGK7DDM_cjs.useTheme; }
 });
 Object.defineProperty(exports, "ActivitySequence", {
   enumerable: true,
-  get: function () { return chunkPBVMEOWI_cjs.ActivitySequence; }
+  get: function () { return chunkDUIWK272_cjs.ActivitySequence; }
 });
 Object.defineProperty(exports, "MultipleChoice", {
   enumerable: true,
-  get: function () { return chunkYXG3UJVG_cjs.MultipleChoice; }
+  get: function () { return chunkBE7R2X3S_cjs.MultipleChoice; }
 });
 Object.defineProperty(exports, "FillInTheBlanks", {
   enumerable: true,
@@ -49,7 +54,7 @@ Object.defineProperty(exports, "FillInTheBlanks", {
 });
 Object.defineProperty(exports, "WrittenResponse", {
   enumerable: true,
-  get: function () { return chunkR3OZ6JHQ_cjs.WrittenResponse; }
+  get: function () { return chunkMDYKYDRN_cjs.WrittenResponse; }
 });
 Object.defineProperty(exports, "StimulusPanel", {
   enumerable: true,
@@ -61,7 +66,7 @@ Object.defineProperty(exports, "useActivityState", {
 });
 Object.defineProperty(exports, "useXAPI", {
   enumerable: true,
-  get: function () { return chunkIYLQSNLE_cjs.useXAPI; }
+  get: function () { return chunkPNNUPUH4_cjs.useXAPI; }
 });
 exports.asRenderable = asRenderable;
 exports.asRenderableSequence = asRenderableSequence;

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/components/types.ts"],"names":[],"mappings":";;;;;;;;;;;;;;AAoJO,SAAS,aACd,QAAA,EACmB;AACnB,EAAA,OAAO,QAAA;AACT;AA4BO,SAAS,qBACd,OAAA,EAC8C;AAC9C,EAAA,OAAO,OAAA;AACT","file":"index.cjs","sourcesContent":["import type {\n  ActivityData,\n  ActivityResult,\n  InteractionEvent,\n  ItemGroup,\n  ItemOutcome,\n  LearnerResponse,\n  RedactedActivityData,\n  SequenceEntry,\n  ThemeTokens,\n} from '@intellectif/lk-core';\n\n/**\n * How an activity is being presented. This is the single switch that decides\n * whether the component may grade, reveal, or submit — the three things a\n * summative exam must take away from the client.\n *\n * - `practice` (default, v1 behaviour): the component owns the attempt. It\n *   scores locally on submit, reveals correctness and feedback, and calls\n *   `onComplete` with a full {@link ActivityResult}.\n * - `exam`: the component NEVER scores and NEVER reveals correctness. Submit\n *   emits the raw learner response through `onSubmit`; the server grades it.\n *   Safe to render redacted data, because nothing here needs the answer key.\n * - `review`: read-only. Renders the learner's submitted answer, and marks\n *   correctness only from an `outcome` the caller supplies (which the server\n *   computed). Nothing is submittable.\n */\nexport type RenderMode = 'practice' | 'exam' | 'review';\n\n/**\n * Makes the answer-key-bearing parts of an activity optional, so a component\n * can render either full activity data OR a `redact()` projection with the\n * same props. Fields the SDK classifies `answer-key` become optional here;\n * a component in `exam` mode must not read them at all.\n */\nexport type Renderable<TData> = Omit<TData, 'scoringStrategy'> & {\n  scoringStrategy?: unknown;\n  /** Present on a `redact()` projection. */\n  redacted?: true;\n};\n\n/**\n * {@link Renderable} DISTRIBUTED over a union of activity types.\n *\n * This distinction is load-bearing, not cosmetic. `Renderable<T>` is built on\n * `Omit`, and `Omit` does not distribute: `Omit<A | B, K>` collapses to the\n * keys A and B have IN COMMON, so `Renderable<ActivityData>` is a single\n * object type carrying only the fields every activity shares. Narrowing it\n * dies with it — after `if (data.type === 'multiple-choice')` the compiler\n * still refuses `data.options`, because the union it would narrow to no\n * longer exists.\n *\n * The conditional below re-distributes, so `RenderableActivity` is a real\n * union of per-type renderables and `.type` narrows again. Anything that\n * accepts \"some renderable activity, I don't know which\" — a custom renderer,\n * a sequence entry — must use THIS, not `Renderable<ActivityData>`.\n */\nexport type RenderableActivity<TData extends ActivityData = ActivityData> = TData extends unknown\n  ? Renderable<TData>\n  : never;\n\n/**\n * Sanitiser for author-supplied rich text (`questionHtml`, `passageHtml`,\n * `promptHtml`). The SDK deliberately ships NO sanitiser — that would add a\n * dependency and, worse, a false promise. Rich text is rendered only when you\n * supply this function; without it the component falls back to the plain-text\n * field, which is always escaped. Fail-safe by construction: the SDK never\n * injects HTML it was not explicitly given a sanitiser for.\n */\nexport type HtmlSanitizer = (html: string) => string;\n\n/**\n * The prop contract shared by every activity component (Req 3.1). Defined\n * here (React-specific) rather than in lk-core, which is React-free.\n *\n * Controlled / uncontrolled follows the React convention: pass `value` +\n * `onChange` to own the learner's answer (restore an in-progress attempt,\n * autosave a delta, drive a review); pass `defaultValue` to seed an\n * uncontrolled component; pass neither for the v1 behaviour.\n */\nexport interface ActivityProps<TData extends ActivityData = ActivityData> {\n  /** Activity content. Accepts a `redact()` projection in `exam` mode. */\n  data: RenderableActivity<TData>;\n  /**\n   * Called when the component scored the attempt itself. Only ever fires in\n   * `practice` mode — in `exam` mode the client does not grade, so there is\n   * no `ActivityResult` to give you; use `onSubmit`.\n   */\n  onComplete?: (result: ActivityResult) => void;\n  /**\n   * Called on submit with the raw learner response and no grade. Fires in\n   * every mode, before `onComplete`, so an exam runner can persist the\n   * response and let the server score it.\n   */\n  onSubmit?: (response: LearnerResponse) => void;\n  /** Controlled value: the learner's current response. */\n  value?: LearnerResponse;\n  /** Initial response for an uncontrolled component (ignored when `value` is set). */\n  defaultValue?: LearnerResponse;\n  /**\n   * Mount the component as already submitted — read at mount only, like any\n   * `default*` prop.\n   *\n   * Restoring an attempt without it reopens a question the learner had already\n   * submitted as answerable, so on a summative paper they can change and\n   * re-submit it. `AttemptState.submittedSlotIds` is what this consumes.\n   */\n  defaultSubmitted?: boolean;\n  /** Fires on every change to the learner's response. Required for a controlled component. */\n  onChange?: (response: LearnerResponse) => void;\n  /** Presentation mode. Defaults to `practice`. */\n  renderMode?: RenderMode;\n  /**\n   * Server-computed outcome, used by `review` mode to mark correctness\n   * without the client ever scoring. Ignored in other modes.\n   */\n  outcome?: ItemOutcome;\n  /** Renders author-supplied rich text when provided. See {@link HtmlSanitizer}. */\n  sanitizeHtml?: HtmlSanitizer;\n  onInteraction?: (event: InteractionEvent) => void;\n  /** Per-instance token overrides, applied as inline CSS vars on the root. */\n  theme?: Partial<ThemeTokens>;\n  locale?: string;\n  disabled?: boolean;\n}\n\n/**\n * Bridges a server-produced `redact()` projection into the `data` prop.\n *\n * `RedactedActivityData` is deliberately index-signature typed in lk-core — it\n * proves a payload is learner-safe, not what shape it has — so TypeScript\n * cannot know it still carries the public fields a renderer needs. This is the\n * SDK's single, documented crossing of that gap, so an exam runner does not\n * have to write `as unknown as` at every call site:\n *\n * ```tsx\n * <MultipleChoice\n *   data={asRenderable<MultipleChoiceData>(redactedFromServer)}\n *   renderMode=\"exam\"\n *   onSubmit={persist}\n * />\n * ```\n *\n * Safe because `exam` mode reads only public fields; the answer-key fields the\n * type claims are exactly the ones the component is forbidden to touch there.\n * A future release will derive per-type redacted interfaces so this becomes\n * unnecessary.\n */\nexport function asRenderable<TData extends ActivityData>(\n  redacted: RedactedActivityData,\n): Renderable<TData> {\n  return redacted as unknown as Renderable<TData>;\n}\n\n/**\n * The same bridge as {@link asRenderable}, for a whole sequence: activities\n * and item groups as a server hands them over, ready for `<ActivitySequence>`.\n *\n * Needed for the same reason and no other. `redactItemGroup` returns\n * `ItemGroup<RedactedActivityData>`, and `RedactedActivityData` is an\n * index-signature type whose fields are all `unknown` — so its `question` is\n * not a `string` and it satisfies no per-type renderable, however the prop is\n * widened. Widening alone cannot fix this; a crossing point is required, and\n * having exactly one keeps `as unknown as` out of consumer code.\n *\n * ```tsx\n * const entries = await fetchExam();            // redacted, server-side\n * <ActivitySequence\n *   activities={asRenderableSequence(entries)}\n *   renderMode=\"exam\"                           // REQUIRED: see below\n *   shuffleSeed={attemptId}\n *   onSubmit={persist}\n * />\n * ```\n *\n * Pass `renderMode=\"exam\"` (or `\"review\"`). Redacted data has no answer key,\n * and the default `practice` mode grades locally — the built-in components\n * throw at render rather than fail at submit time, so a mis-wired exam item is\n * loud, not silent.\n */\nexport function asRenderableSequence(\n  entries: readonly (RedactedActivityData | RedactedItemGroupData)[],\n): readonly SequenceEntry<RenderableActivity>[] {\n  return entries as unknown as readonly SequenceEntry<RenderableActivity>[];\n}\n\n/** Structural shape of a `redactItemGroup()` projection, as it arrives from a server. */\ntype RedactedItemGroupData = ItemGroup<RedactedActivityData> & { redacted: true };\n"]}
+{"version":3,"sources":["../src/components/types.ts"],"names":[],"mappings":";;;;;;;;;;;;;;AAgKO,SAAS,aACd,QAAA,EACmB;AACnB,EAAA,OAAO,QAAA;AACT;AAgCO,SAAS,qBACd,OAAA,EAC8C;AAC9C,EAAA,OAAO,OAAA;AACT","file":"index.cjs","sourcesContent":["import type {\n  ActivityData,\n  ActivityResult,\n  InteractionEvent,\n  ItemGroup,\n  ItemOutcome,\n  LearnerResponse,\n  RedactedActivityData,\n  SequenceEntry,\n  ThemeTokens,\n} from '@intellectif/lk-core';\n\n/**\n * How an activity is being presented. This is the single switch that decides\n * whether the component may grade, reveal, or submit — the three things a\n * summative exam must take away from the client.\n *\n * - `practice` (default, and the only behaviour before `renderMode` existed):\n *   the component owns the attempt. It\n *   scores locally on submit, reveals correctness and feedback, and calls\n *   `onComplete` with a full {@link ActivityResult}.\n * - `exam`: the component NEVER scores and NEVER reveals correctness. Submit\n *   emits the raw learner response through `onSubmit`; the server grades it.\n *   Safe to render redacted data, because nothing here needs the answer key.\n * - `review`: read-only. Renders the learner's submitted answer, and marks\n *   correctness only from an `outcome` the caller supplies (which the server\n *   computed). Nothing is submittable.\n */\nexport type RenderMode = 'practice' | 'exam' | 'review';\n\n/**\n * Makes the answer-key-bearing parts of an activity optional, so a component\n * can render either full activity data OR a `redact()` projection with the\n * same props. Fields the SDK classifies `answer-key` become optional here;\n * a component in `exam` mode must not read them at all.\n */\nexport type Renderable<TData> = Omit<TData, 'scoringStrategy'> & {\n  scoringStrategy?: unknown;\n  /** Present on a `redact()` projection. */\n  redacted?: true;\n};\n\n/**\n * {@link Renderable} DISTRIBUTED over a union of activity types.\n *\n * This distinction is load-bearing, not cosmetic. `Renderable<T>` is built on\n * `Omit`, and `Omit` does not distribute: `Omit<A | B, K>` collapses to the\n * keys A and B have IN COMMON, so `Renderable<ActivityData>` is a single\n * object type carrying only the fields every activity shares. Narrowing it\n * dies with it — after `if (data.type === 'multiple-choice')` the compiler\n * still refuses `data.options`, because the union it would narrow to no\n * longer exists.\n *\n * The conditional below re-distributes, so `RenderableActivity` is a real\n * union of per-type renderables and `.type` narrows again. Anything that\n * accepts \"some renderable activity, I don't know which\" — a custom renderer,\n * a sequence entry — must use THIS, not `Renderable<ActivityData>`.\n */\nexport type RenderableActivity<TData extends ActivityData = ActivityData> = TData extends unknown\n  ? Renderable<TData>\n  : never;\n\n/**\n * Sanitiser for author-supplied rich text (`questionHtml`, `promptHtml`, and a\n * stimulus's `bodyHtml`). The SDK deliberately ships NO sanitiser — that would\n * add a dependency and, worse, a false promise. Rich text is rendered only when\n * you supply this function; without it the component falls back to the\n * plain-text field, which is always escaped. Fail-safe by construction: the SDK\n * never injects HTML it was not explicitly given a sanitiser for.\n *\n * `FillInTheBlanks.passageHtml` is the one exception, and is **never**\n * rendered: the passage hosts the answer inputs, so it cannot be split at the\n * `{{blank}}` placeholders without voiding the sanitiser. The plain `passage`\n * is always used, and passing `passageHtml` warns in development.\n */\nexport type HtmlSanitizer = (html: string) => string;\n\n/**\n * The prop contract shared by every activity component (Req 3.1). Defined\n * here (React-specific) rather than in lk-core, which is React-free.\n *\n * Controlled / uncontrolled follows the React convention: pass `value` +\n * `onChange` to own the learner's answer (restore an in-progress attempt,\n * autosave a delta, drive a review); pass `defaultValue` to seed an\n * uncontrolled component; pass neither to keep the pre-2.1.0 behaviour, where\n * the component owns the answer outright.\n */\nexport interface ActivityProps<TData extends ActivityData = ActivityData> {\n  /** Activity content. Accepts a `redact()` projection in `exam` mode. */\n  data: RenderableActivity<TData>;\n  /**\n   * Called when the component scored the attempt itself. Only ever fires in\n   * `practice` mode — in `exam` mode the client does not grade, so there is\n   * no `ActivityResult` to give you; use `onSubmit`.\n   */\n  onComplete?: (result: ActivityResult) => void;\n  /**\n   * Called on submit with the raw learner response and no grade. Fires in\n   * every mode, before `onComplete`, so an exam runner can persist the\n   * response and let the server score it.\n   */\n  onSubmit?: (response: LearnerResponse) => void;\n  /** Controlled value: the learner's current response. */\n  value?: LearnerResponse;\n  /** Initial response for an uncontrolled component (ignored when `value` is set). */\n  defaultValue?: LearnerResponse;\n  /**\n   * Mount the component as already submitted — read at mount only, like any\n   * `default*` prop.\n   *\n   * Restoring an attempt without it reopens a question the learner had already\n   * submitted as answerable, so on a summative paper they can change and\n   * re-submit it. `AttemptState.submittedSlotIds` is what this consumes.\n   */\n  defaultSubmitted?: boolean;\n  /** Fires on every change to the learner's response. Required for a controlled component. */\n  onChange?: (response: LearnerResponse) => void;\n  /** Presentation mode. Defaults to `practice`. */\n  renderMode?: RenderMode;\n  /**\n   * Server-computed outcome, used by `review` mode to mark correctness\n   * without the client ever scoring. Ignored in other modes.\n   */\n  outcome?: ItemOutcome;\n  /** Renders author-supplied rich text when provided. See {@link HtmlSanitizer}. */\n  sanitizeHtml?: HtmlSanitizer;\n  onInteraction?: (event: InteractionEvent) => void;\n  /** Per-instance token overrides, applied as inline CSS vars on the root. */\n  theme?: Partial<ThemeTokens>;\n  locale?: string;\n  disabled?: boolean;\n}\n\n/**\n * Bridges a server-produced `redact()` projection into the `data` prop.\n *\n * `RedactedActivityData` is deliberately index-signature typed in lk-core — it\n * proves a payload is learner-safe, not what shape it has — so TypeScript\n * cannot know it still carries the public fields a renderer needs. This is the\n * SDK's single, documented crossing of that gap, so an exam runner does not\n * have to write `as unknown as` at every call site:\n *\n * ```tsx\n * <MultipleChoice\n *   data={asRenderable<MultipleChoiceData>(redactedFromServer)}\n *   renderMode=\"exam\"\n *   onSubmit={persist}\n * />\n * ```\n *\n * Safe because `exam` mode reads only public fields; the answer-key fields the\n * type claims are exactly the ones the component is forbidden to touch there.\n *\n * Per-type redacted interfaces (`RedactedMultipleChoiceData`, …) ship from\n * lk-core since 0.6.0, but they are not yet *assignable* to `data`:\n * {@link Renderable} widens `scoringStrategy` and leaves nested answer-key\n * fields (`options[].isCorrect`, `blanks[].acceptedAnswers`) required, so a\n * real redacted payload still needs this bridge. Closing that gap is tracked\n * in the roadmap.\n */\nexport function asRenderable<TData extends ActivityData>(\n  redacted: RedactedActivityData,\n): Renderable<TData> {\n  return redacted as unknown as Renderable<TData>;\n}\n\n/**\n * The same bridge as {@link asRenderable}, for a whole sequence: activities\n * and item groups as a server hands them over, ready for `<ActivitySequence>`.\n *\n * Needed for the same reason and no other. `redactItemGroup` returns\n * `ItemGroup<RedactedActivityData>`, and `RedactedActivityData` is an\n * index-signature type whose fields are all `unknown` — so its `question` is\n * not a `string` and it satisfies no per-type renderable, however the prop is\n * widened. Widening alone cannot fix this; a crossing point is required, and\n * having exactly one keeps `as unknown as` out of consumer code.\n *\n * ```tsx\n * const entries = await fetchExam();            // redacted, server-side\n * <ActivitySequence\n *   activities={asRenderableSequence(entries)}\n *   renderMode=\"exam\"                           // REQUIRED: see below\n *   shuffleSeed={attemptId}\n *   onSubmit={persist}\n * />\n * ```\n *\n * Pass `renderMode=\"exam\"` (or `\"review\"`). Redacted data has no answer key,\n * and the default `practice` mode grades locally — so `<MultipleChoice>` and\n * `<FillInTheBlanks>` throw at render rather than fail at submit time.\n *\n * `<WrittenResponse>` is the exception: it never grades on the client and has\n * no such guard, so a redacted essay renders and stays answerable in\n * `practice`. A mis-wired essay item is therefore SILENT — set `renderMode`\n * explicitly rather than relying on the throw.\n */\nexport function asRenderableSequence(\n  entries: readonly (RedactedActivityData | RedactedItemGroupData)[],\n): readonly SequenceEntry<RenderableActivity>[] {\n  return entries as unknown as readonly SequenceEntry<RenderableActivity>[];\n}\n\n/** Structural shape of a `redactItemGroup()` projection, as it arrives from a server. */\ntype RedactedItemGroupData = ItemGroup<RedactedActivityData> & { redacted: true };\n"]}

package/dist/index.d.cts

@@ -2,12 +2,12 @@ export { ActivityRenderer, ActivitySequence, ActivitySequenceProps, SequenceItem
 export { FillInTheBlanks, FillInTheBlanksProps } from './components/FillInTheBlanks.cjs';
 export { MultipleChoice, MultipleChoiceProps } from './components/MultipleChoice.cjs';
 export { StimulusPanel, StimulusPanelProps } from './components/StimulusPanel.cjs';
-export { A as ActivityProps, H as HtmlSanitizer, R as RenderMode, a as Renderable, b as RenderableActivity, c as asRenderable, d as asRenderableSequence } from './types-DlHmPLbD.cjs';
+export { A as ActivityProps, H as HtmlSanitizer, R as RenderMode, a as Renderable, b as RenderableActivity, c as asRenderable, d as asRenderableSequence } from './types-9iS1Vs2I.cjs';
 export { WrittenResponse } from './components/WrittenResponse.cjs';
 export { ActivityState, UseActivityStateResult, useActivityState } from './hooks/useActivityState.cjs';
 export { UseXAPIResult, useXAPI } from './hooks/useXAPI.cjs';
-export { ThemeProvider, ThemeProviderProps, darkTheme, defaultTheme, useTheme } from './theme/ThemeProvider.cjs';
-export { W as WrittenResponseProps, a as WrittenResponseSubmission } from './WrittenResponse-BfpzfLlR.cjs';
+export { TailwindThemeExtension, ThemeProvider, ThemeProviderProps, createTailwindTheme, darkTheme, defaultTheme, useTheme } from './theme/ThemeProvider.cjs';
+export { W as WrittenResponseProps, a as WrittenResponseSubmission } from './WrittenResponse-BXHidIaK.cjs';
 import '@intellectif/lk-core';
 import 'react';
 import 'react/jsx-runtime';

package/dist/index.d.ts

@@ -2,12 +2,12 @@ export { ActivityRenderer, ActivitySequence, ActivitySequenceProps, SequenceItem
 export { FillInTheBlanks, FillInTheBlanksProps } from './components/FillInTheBlanks.js';
 export { MultipleChoice, MultipleChoiceProps } from './components/MultipleChoice.js';
 export { StimulusPanel, StimulusPanelProps } from './components/StimulusPanel.js';
-export { A as ActivityProps, H as HtmlSanitizer, R as RenderMode, a as Renderable, b as RenderableActivity, c as asRenderable, d as asRenderableSequence } from './types-DlHmPLbD.js';
+export { A as ActivityProps, H as HtmlSanitizer, R as RenderMode, a as Renderable, b as RenderableActivity, c as asRenderable, d as asRenderableSequence } from './types-9iS1Vs2I.js';
 export { WrittenResponse } from './components/WrittenResponse.js';
 export { ActivityState, UseActivityStateResult, useActivityState } from './hooks/useActivityState.js';
 export { UseXAPIResult, useXAPI } from './hooks/useXAPI.js';
-export { ThemeProvider, ThemeProviderProps, darkTheme, defaultTheme, useTheme } from './theme/ThemeProvider.js';
-export { W as WrittenResponseProps, a as WrittenResponseSubmission } from './WrittenResponse-C3GIWErG.js';
+export { TailwindThemeExtension, ThemeProvider, ThemeProviderProps, createTailwindTheme, darkTheme, defaultTheme, useTheme } from './theme/ThemeProvider.js';
+export { W as WrittenResponseProps, a as WrittenResponseSubmission } from './WrittenResponse-DJYGuMKk.js';
 import '@intellectif/lk-core';
 import 'react';
 import 'react/jsx-runtime';

package/dist/index.js

@@ -1,13 +1,14 @@
-export { ThemeProvider, darkTheme, defaultTheme, useTheme } from './chunk-B3FUUKZ2.js';
-export { ActivitySequence } from './chunk-OQGBAQL2.js';
-export { MultipleChoice } from './chunk-5TUTJ4R3.js';
+'use client';
+export { ThemeProvider, createTailwindTheme, darkTheme, defaultTheme, useTheme } from './chunk-DQNVAXG6.js';
+export { ActivitySequence } from './chunk-IUODGQXE.js';
+export { MultipleChoice } from './chunk-ZLUMUJUQ.js';
 export { FillInTheBlanks } from './chunk-57E3E2H4.js';
-export { WrittenResponse } from './chunk-BQHDQ33H.js';
+export { WrittenResponse } from './chunk-MDZMKC27.js';
 import './chunk-6F4X2NKL.js';
 export { StimulusPanel } from './chunk-UQ3BBEIT.js';
 import './chunk-GB5URWM4.js';
 export { useActivityState } from './chunk-6N43WDVG.js';
-export { useXAPI } from './chunk-E4MNA2IQ.js';
+export { useXAPI } from './chunk-2TW6WLBC.js';
 
 // src/components/types.ts
 function asRenderable(redacted) {

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/components/types.ts"],"names":[],"mappings":";;;;;;;;;;;;AAoJO,SAAS,aACd,QAAA,EACmB;AACnB,EAAA,OAAO,QAAA;AACT;AA4BO,SAAS,qBACd,OAAA,EAC8C;AAC9C,EAAA,OAAO,OAAA;AACT","file":"index.js","sourcesContent":["import type {\n  ActivityData,\n  ActivityResult,\n  InteractionEvent,\n  ItemGroup,\n  ItemOutcome,\n  LearnerResponse,\n  RedactedActivityData,\n  SequenceEntry,\n  ThemeTokens,\n} from '@intellectif/lk-core';\n\n/**\n * How an activity is being presented. This is the single switch that decides\n * whether the component may grade, reveal, or submit — the three things a\n * summative exam must take away from the client.\n *\n * - `practice` (default, v1 behaviour): the component owns the attempt. It\n *   scores locally on submit, reveals correctness and feedback, and calls\n *   `onComplete` with a full {@link ActivityResult}.\n * - `exam`: the component NEVER scores and NEVER reveals correctness. Submit\n *   emits the raw learner response through `onSubmit`; the server grades it.\n *   Safe to render redacted data, because nothing here needs the answer key.\n * - `review`: read-only. Renders the learner's submitted answer, and marks\n *   correctness only from an `outcome` the caller supplies (which the server\n *   computed). Nothing is submittable.\n */\nexport type RenderMode = 'practice' | 'exam' | 'review';\n\n/**\n * Makes the answer-key-bearing parts of an activity optional, so a component\n * can render either full activity data OR a `redact()` projection with the\n * same props. Fields the SDK classifies `answer-key` become optional here;\n * a component in `exam` mode must not read them at all.\n */\nexport type Renderable<TData> = Omit<TData, 'scoringStrategy'> & {\n  scoringStrategy?: unknown;\n  /** Present on a `redact()` projection. */\n  redacted?: true;\n};\n\n/**\n * {@link Renderable} DISTRIBUTED over a union of activity types.\n *\n * This distinction is load-bearing, not cosmetic. `Renderable<T>` is built on\n * `Omit`, and `Omit` does not distribute: `Omit<A | B, K>` collapses to the\n * keys A and B have IN COMMON, so `Renderable<ActivityData>` is a single\n * object type carrying only the fields every activity shares. Narrowing it\n * dies with it — after `if (data.type === 'multiple-choice')` the compiler\n * still refuses `data.options`, because the union it would narrow to no\n * longer exists.\n *\n * The conditional below re-distributes, so `RenderableActivity` is a real\n * union of per-type renderables and `.type` narrows again. Anything that\n * accepts \"some renderable activity, I don't know which\" — a custom renderer,\n * a sequence entry — must use THIS, not `Renderable<ActivityData>`.\n */\nexport type RenderableActivity<TData extends ActivityData = ActivityData> = TData extends unknown\n  ? Renderable<TData>\n  : never;\n\n/**\n * Sanitiser for author-supplied rich text (`questionHtml`, `passageHtml`,\n * `promptHtml`). The SDK deliberately ships NO sanitiser — that would add a\n * dependency and, worse, a false promise. Rich text is rendered only when you\n * supply this function; without it the component falls back to the plain-text\n * field, which is always escaped. Fail-safe by construction: the SDK never\n * injects HTML it was not explicitly given a sanitiser for.\n */\nexport type HtmlSanitizer = (html: string) => string;\n\n/**\n * The prop contract shared by every activity component (Req 3.1). Defined\n * here (React-specific) rather than in lk-core, which is React-free.\n *\n * Controlled / uncontrolled follows the React convention: pass `value` +\n * `onChange` to own the learner's answer (restore an in-progress attempt,\n * autosave a delta, drive a review); pass `defaultValue` to seed an\n * uncontrolled component; pass neither for the v1 behaviour.\n */\nexport interface ActivityProps<TData extends ActivityData = ActivityData> {\n  /** Activity content. Accepts a `redact()` projection in `exam` mode. */\n  data: RenderableActivity<TData>;\n  /**\n   * Called when the component scored the attempt itself. Only ever fires in\n   * `practice` mode — in `exam` mode the client does not grade, so there is\n   * no `ActivityResult` to give you; use `onSubmit`.\n   */\n  onComplete?: (result: ActivityResult) => void;\n  /**\n   * Called on submit with the raw learner response and no grade. Fires in\n   * every mode, before `onComplete`, so an exam runner can persist the\n   * response and let the server score it.\n   */\n  onSubmit?: (response: LearnerResponse) => void;\n  /** Controlled value: the learner's current response. */\n  value?: LearnerResponse;\n  /** Initial response for an uncontrolled component (ignored when `value` is set). */\n  defaultValue?: LearnerResponse;\n  /**\n   * Mount the component as already submitted — read at mount only, like any\n   * `default*` prop.\n   *\n   * Restoring an attempt without it reopens a question the learner had already\n   * submitted as answerable, so on a summative paper they can change and\n   * re-submit it. `AttemptState.submittedSlotIds` is what this consumes.\n   */\n  defaultSubmitted?: boolean;\n  /** Fires on every change to the learner's response. Required for a controlled component. */\n  onChange?: (response: LearnerResponse) => void;\n  /** Presentation mode. Defaults to `practice`. */\n  renderMode?: RenderMode;\n  /**\n   * Server-computed outcome, used by `review` mode to mark correctness\n   * without the client ever scoring. Ignored in other modes.\n   */\n  outcome?: ItemOutcome;\n  /** Renders author-supplied rich text when provided. See {@link HtmlSanitizer}. */\n  sanitizeHtml?: HtmlSanitizer;\n  onInteraction?: (event: InteractionEvent) => void;\n  /** Per-instance token overrides, applied as inline CSS vars on the root. */\n  theme?: Partial<ThemeTokens>;\n  locale?: string;\n  disabled?: boolean;\n}\n\n/**\n * Bridges a server-produced `redact()` projection into the `data` prop.\n *\n * `RedactedActivityData` is deliberately index-signature typed in lk-core — it\n * proves a payload is learner-safe, not what shape it has — so TypeScript\n * cannot know it still carries the public fields a renderer needs. This is the\n * SDK's single, documented crossing of that gap, so an exam runner does not\n * have to write `as unknown as` at every call site:\n *\n * ```tsx\n * <MultipleChoice\n *   data={asRenderable<MultipleChoiceData>(redactedFromServer)}\n *   renderMode=\"exam\"\n *   onSubmit={persist}\n * />\n * ```\n *\n * Safe because `exam` mode reads only public fields; the answer-key fields the\n * type claims are exactly the ones the component is forbidden to touch there.\n * A future release will derive per-type redacted interfaces so this becomes\n * unnecessary.\n */\nexport function asRenderable<TData extends ActivityData>(\n  redacted: RedactedActivityData,\n): Renderable<TData> {\n  return redacted as unknown as Renderable<TData>;\n}\n\n/**\n * The same bridge as {@link asRenderable}, for a whole sequence: activities\n * and item groups as a server hands them over, ready for `<ActivitySequence>`.\n *\n * Needed for the same reason and no other. `redactItemGroup` returns\n * `ItemGroup<RedactedActivityData>`, and `RedactedActivityData` is an\n * index-signature type whose fields are all `unknown` — so its `question` is\n * not a `string` and it satisfies no per-type renderable, however the prop is\n * widened. Widening alone cannot fix this; a crossing point is required, and\n * having exactly one keeps `as unknown as` out of consumer code.\n *\n * ```tsx\n * const entries = await fetchExam();            // redacted, server-side\n * <ActivitySequence\n *   activities={asRenderableSequence(entries)}\n *   renderMode=\"exam\"                           // REQUIRED: see below\n *   shuffleSeed={attemptId}\n *   onSubmit={persist}\n * />\n * ```\n *\n * Pass `renderMode=\"exam\"` (or `\"review\"`). Redacted data has no answer key,\n * and the default `practice` mode grades locally — the built-in components\n * throw at render rather than fail at submit time, so a mis-wired exam item is\n * loud, not silent.\n */\nexport function asRenderableSequence(\n  entries: readonly (RedactedActivityData | RedactedItemGroupData)[],\n): readonly SequenceEntry<RenderableActivity>[] {\n  return entries as unknown as readonly SequenceEntry<RenderableActivity>[];\n}\n\n/** Structural shape of a `redactItemGroup()` projection, as it arrives from a server. */\ntype RedactedItemGroupData = ItemGroup<RedactedActivityData> & { redacted: true };\n"]}
+{"version":3,"sources":["../src/components/types.ts"],"names":[],"mappings":";;;;;;;;;;;;AAgKO,SAAS,aACd,QAAA,EACmB;AACnB,EAAA,OAAO,QAAA;AACT;AAgCO,SAAS,qBACd,OAAA,EAC8C;AAC9C,EAAA,OAAO,OAAA;AACT","file":"index.js","sourcesContent":["import type {\n  ActivityData,\n  ActivityResult,\n  InteractionEvent,\n  ItemGroup,\n  ItemOutcome,\n  LearnerResponse,\n  RedactedActivityData,\n  SequenceEntry,\n  ThemeTokens,\n} from '@intellectif/lk-core';\n\n/**\n * How an activity is being presented. This is the single switch that decides\n * whether the component may grade, reveal, or submit — the three things a\n * summative exam must take away from the client.\n *\n * - `practice` (default, and the only behaviour before `renderMode` existed):\n *   the component owns the attempt. It\n *   scores locally on submit, reveals correctness and feedback, and calls\n *   `onComplete` with a full {@link ActivityResult}.\n * - `exam`: the component NEVER scores and NEVER reveals correctness. Submit\n *   emits the raw learner response through `onSubmit`; the server grades it.\n *   Safe to render redacted data, because nothing here needs the answer key.\n * - `review`: read-only. Renders the learner's submitted answer, and marks\n *   correctness only from an `outcome` the caller supplies (which the server\n *   computed). Nothing is submittable.\n */\nexport type RenderMode = 'practice' | 'exam' | 'review';\n\n/**\n * Makes the answer-key-bearing parts of an activity optional, so a component\n * can render either full activity data OR a `redact()` projection with the\n * same props. Fields the SDK classifies `answer-key` become optional here;\n * a component in `exam` mode must not read them at all.\n */\nexport type Renderable<TData> = Omit<TData, 'scoringStrategy'> & {\n  scoringStrategy?: unknown;\n  /** Present on a `redact()` projection. */\n  redacted?: true;\n};\n\n/**\n * {@link Renderable} DISTRIBUTED over a union of activity types.\n *\n * This distinction is load-bearing, not cosmetic. `Renderable<T>` is built on\n * `Omit`, and `Omit` does not distribute: `Omit<A | B, K>` collapses to the\n * keys A and B have IN COMMON, so `Renderable<ActivityData>` is a single\n * object type carrying only the fields every activity shares. Narrowing it\n * dies with it — after `if (data.type === 'multiple-choice')` the compiler\n * still refuses `data.options`, because the union it would narrow to no\n * longer exists.\n *\n * The conditional below re-distributes, so `RenderableActivity` is a real\n * union of per-type renderables and `.type` narrows again. Anything that\n * accepts \"some renderable activity, I don't know which\" — a custom renderer,\n * a sequence entry — must use THIS, not `Renderable<ActivityData>`.\n */\nexport type RenderableActivity<TData extends ActivityData = ActivityData> = TData extends unknown\n  ? Renderable<TData>\n  : never;\n\n/**\n * Sanitiser for author-supplied rich text (`questionHtml`, `promptHtml`, and a\n * stimulus's `bodyHtml`). The SDK deliberately ships NO sanitiser — that would\n * add a dependency and, worse, a false promise. Rich text is rendered only when\n * you supply this function; without it the component falls back to the\n * plain-text field, which is always escaped. Fail-safe by construction: the SDK\n * never injects HTML it was not explicitly given a sanitiser for.\n *\n * `FillInTheBlanks.passageHtml` is the one exception, and is **never**\n * rendered: the passage hosts the answer inputs, so it cannot be split at the\n * `{{blank}}` placeholders without voiding the sanitiser. The plain `passage`\n * is always used, and passing `passageHtml` warns in development.\n */\nexport type HtmlSanitizer = (html: string) => string;\n\n/**\n * The prop contract shared by every activity component (Req 3.1). Defined\n * here (React-specific) rather than in lk-core, which is React-free.\n *\n * Controlled / uncontrolled follows the React convention: pass `value` +\n * `onChange` to own the learner's answer (restore an in-progress attempt,\n * autosave a delta, drive a review); pass `defaultValue` to seed an\n * uncontrolled component; pass neither to keep the pre-2.1.0 behaviour, where\n * the component owns the answer outright.\n */\nexport interface ActivityProps<TData extends ActivityData = ActivityData> {\n  /** Activity content. Accepts a `redact()` projection in `exam` mode. */\n  data: RenderableActivity<TData>;\n  /**\n   * Called when the component scored the attempt itself. Only ever fires in\n   * `practice` mode — in `exam` mode the client does not grade, so there is\n   * no `ActivityResult` to give you; use `onSubmit`.\n   */\n  onComplete?: (result: ActivityResult) => void;\n  /**\n   * Called on submit with the raw learner response and no grade. Fires in\n   * every mode, before `onComplete`, so an exam runner can persist the\n   * response and let the server score it.\n   */\n  onSubmit?: (response: LearnerResponse) => void;\n  /** Controlled value: the learner's current response. */\n  value?: LearnerResponse;\n  /** Initial response for an uncontrolled component (ignored when `value` is set). */\n  defaultValue?: LearnerResponse;\n  /**\n   * Mount the component as already submitted — read at mount only, like any\n   * `default*` prop.\n   *\n   * Restoring an attempt without it reopens a question the learner had already\n   * submitted as answerable, so on a summative paper they can change and\n   * re-submit it. `AttemptState.submittedSlotIds` is what this consumes.\n   */\n  defaultSubmitted?: boolean;\n  /** Fires on every change to the learner's response. Required for a controlled component. */\n  onChange?: (response: LearnerResponse) => void;\n  /** Presentation mode. Defaults to `practice`. */\n  renderMode?: RenderMode;\n  /**\n   * Server-computed outcome, used by `review` mode to mark correctness\n   * without the client ever scoring. Ignored in other modes.\n   */\n  outcome?: ItemOutcome;\n  /** Renders author-supplied rich text when provided. See {@link HtmlSanitizer}. */\n  sanitizeHtml?: HtmlSanitizer;\n  onInteraction?: (event: InteractionEvent) => void;\n  /** Per-instance token overrides, applied as inline CSS vars on the root. */\n  theme?: Partial<ThemeTokens>;\n  locale?: string;\n  disabled?: boolean;\n}\n\n/**\n * Bridges a server-produced `redact()` projection into the `data` prop.\n *\n * `RedactedActivityData` is deliberately index-signature typed in lk-core — it\n * proves a payload is learner-safe, not what shape it has — so TypeScript\n * cannot know it still carries the public fields a renderer needs. This is the\n * SDK's single, documented crossing of that gap, so an exam runner does not\n * have to write `as unknown as` at every call site:\n *\n * ```tsx\n * <MultipleChoice\n *   data={asRenderable<MultipleChoiceData>(redactedFromServer)}\n *   renderMode=\"exam\"\n *   onSubmit={persist}\n * />\n * ```\n *\n * Safe because `exam` mode reads only public fields; the answer-key fields the\n * type claims are exactly the ones the component is forbidden to touch there.\n *\n * Per-type redacted interfaces (`RedactedMultipleChoiceData`, …) ship from\n * lk-core since 0.6.0, but they are not yet *assignable* to `data`:\n * {@link Renderable} widens `scoringStrategy` and leaves nested answer-key\n * fields (`options[].isCorrect`, `blanks[].acceptedAnswers`) required, so a\n * real redacted payload still needs this bridge. Closing that gap is tracked\n * in the roadmap.\n */\nexport function asRenderable<TData extends ActivityData>(\n  redacted: RedactedActivityData,\n): Renderable<TData> {\n  return redacted as unknown as Renderable<TData>;\n}\n\n/**\n * The same bridge as {@link asRenderable}, for a whole sequence: activities\n * and item groups as a server hands them over, ready for `<ActivitySequence>`.\n *\n * Needed for the same reason and no other. `redactItemGroup` returns\n * `ItemGroup<RedactedActivityData>`, and `RedactedActivityData` is an\n * index-signature type whose fields are all `unknown` — so its `question` is\n * not a `string` and it satisfies no per-type renderable, however the prop is\n * widened. Widening alone cannot fix this; a crossing point is required, and\n * having exactly one keeps `as unknown as` out of consumer code.\n *\n * ```tsx\n * const entries = await fetchExam();            // redacted, server-side\n * <ActivitySequence\n *   activities={asRenderableSequence(entries)}\n *   renderMode=\"exam\"                           // REQUIRED: see below\n *   shuffleSeed={attemptId}\n *   onSubmit={persist}\n * />\n * ```\n *\n * Pass `renderMode=\"exam\"` (or `\"review\"`). Redacted data has no answer key,\n * and the default `practice` mode grades locally — so `<MultipleChoice>` and\n * `<FillInTheBlanks>` throw at render rather than fail at submit time.\n *\n * `<WrittenResponse>` is the exception: it never grades on the client and has\n * no such guard, so a redacted essay renders and stays answerable in\n * `practice`. A mis-wired essay item is therefore SILENT — set `renderMode`\n * explicitly rather than relying on the throw.\n */\nexport function asRenderableSequence(\n  entries: readonly (RedactedActivityData | RedactedItemGroupData)[],\n): readonly SequenceEntry<RenderableActivity>[] {\n  return entries as unknown as readonly SequenceEntry<RenderableActivity>[];\n}\n\n/** Structural shape of a `redactItemGroup()` projection, as it arrives from a server. */\ntype RedactedItemGroupData = ItemGroup<RedactedActivityData> & { redacted: true };\n"]}

package/dist/theme/ThemeProvider.cjs

@@ -1,24 +1,29 @@
+'use client';
 'use strict';
 
-var chunkCPF2JJG6_cjs = require('../chunk-CPF2JJG6.cjs');
+var chunkAMGK7DDM_cjs = require('../chunk-AMGK7DDM.cjs');
 
 
 
 Object.defineProperty(exports, "ThemeProvider", {
   enumerable: true,
-  get: function () { return chunkCPF2JJG6_cjs.ThemeProvider; }
+  get: function () { return chunkAMGK7DDM_cjs.ThemeProvider; }
+});
+Object.defineProperty(exports, "createTailwindTheme", {
+  enumerable: true,
+  get: function () { return chunkAMGK7DDM_cjs.createTailwindTheme; }
 });
 Object.defineProperty(exports, "darkTheme", {
   enumerable: true,
-  get: function () { return chunkCPF2JJG6_cjs.darkTheme; }
+  get: function () { return chunkAMGK7DDM_cjs.darkTheme; }
 });
 Object.defineProperty(exports, "defaultTheme", {
   enumerable: true,
-  get: function () { return chunkCPF2JJG6_cjs.defaultTheme; }
+  get: function () { return chunkAMGK7DDM_cjs.defaultTheme; }
 });
 Object.defineProperty(exports, "useTheme", {
   enumerable: true,
-  get: function () { return chunkCPF2JJG6_cjs.useTheme; }
+  get: function () { return chunkAMGK7DDM_cjs.useTheme; }
 });
 //# sourceMappingURL=ThemeProvider.cjs.map
 //# sourceMappingURL=ThemeProvider.cjs.map

package/dist/theme/ThemeProvider.d.cts

@@ -9,6 +9,26 @@ import { ReactNode } from 'react';
  */
 declare const darkTheme: Partial<ThemeTokens>;
 
+/**
+ * Shape consumed by a Tailwind config's `theme.extend`. Every entry is a
+ * `var(--lk-token, <fallback>)` reference: the var keeps utilities live
+ * (ThemeProvider / dark-mode override at runtime); the fallback makes them
+ * work with zero setup (no provider, no `defaults.css` import).
+ */
+interface TailwindThemeExtension {
+    colors: Record<string, string>;
+    spacing: Record<string, string>;
+    borderRadius: Record<string, string>;
+    fontFamily: Record<string, string>;
+    fontSize: Record<string, string>;
+}
+/**
+ * Converts SDK theme tokens into a Tailwind `theme.extend` object so Tailwind
+ * projects consume the same `--lk-*` tokens as the components — one shared
+ * source of truth rather than a parallel, conflicting palette.
+ */
+declare function createTailwindTheme(theme: Partial<ThemeTokens>): TailwindThemeExtension;
+
 /**
  * Canonical default theme token values. `defaults.css` mirrors these exactly.
  * Palette is a neutral monochrome (ElevenLabs-like) so the SDK is brand-neutral
@@ -36,4 +56,4 @@ declare function ThemeProvider({ theme, children }: ThemeProviderProps): react_j
 /** Returns the currently active theme tokens (defaults when no provider). */
 declare function useTheme(): ThemeTokens;
 
-export { ThemeProvider, type ThemeProviderProps, darkTheme, defaultTheme, useTheme };
+export { type TailwindThemeExtension, ThemeProvider, type ThemeProviderProps, createTailwindTheme, darkTheme, defaultTheme, useTheme };

package/dist/theme/ThemeProvider.d.ts

@@ -9,6 +9,26 @@ import { ReactNode } from 'react';
  */
 declare const darkTheme: Partial<ThemeTokens>;
 
+/**
+ * Shape consumed by a Tailwind config's `theme.extend`. Every entry is a
+ * `var(--lk-token, <fallback>)` reference: the var keeps utilities live
+ * (ThemeProvider / dark-mode override at runtime); the fallback makes them
+ * work with zero setup (no provider, no `defaults.css` import).
+ */
+interface TailwindThemeExtension {
+    colors: Record<string, string>;
+    spacing: Record<string, string>;
+    borderRadius: Record<string, string>;
+    fontFamily: Record<string, string>;
+    fontSize: Record<string, string>;
+}
+/**
+ * Converts SDK theme tokens into a Tailwind `theme.extend` object so Tailwind
+ * projects consume the same `--lk-*` tokens as the components — one shared
+ * source of truth rather than a parallel, conflicting palette.
+ */
+declare function createTailwindTheme(theme: Partial<ThemeTokens>): TailwindThemeExtension;
+
 /**
  * Canonical default theme token values. `defaults.css` mirrors these exactly.
  * Palette is a neutral monochrome (ElevenLabs-like) so the SDK is brand-neutral
@@ -36,4 +56,4 @@ declare function ThemeProvider({ theme, children }: ThemeProviderProps): react_j
 /** Returns the currently active theme tokens (defaults when no provider). */
 declare function useTheme(): ThemeTokens;
 
-export { ThemeProvider, type ThemeProviderProps, darkTheme, defaultTheme, useTheme };
+export { type TailwindThemeExtension, ThemeProvider, type ThemeProviderProps, createTailwindTheme, darkTheme, defaultTheme, useTheme };

package/dist/theme/ThemeProvider.js

@@ -1,3 +1,4 @@
-export { ThemeProvider, darkTheme, defaultTheme, useTheme } from '../chunk-B3FUUKZ2.js';
+'use client';
+export { ThemeProvider, createTailwindTheme, darkTheme, defaultTheme, useTheme } from '../chunk-DQNVAXG6.js';
 //# sourceMappingURL=ThemeProvider.js.map
 //# sourceMappingURL=ThemeProvider.js.map

package/dist/theme/skin.css

@@ -409,7 +409,7 @@
   .lk-wr-prompt {
     margin: 0;
     color: var(--lk-color-text);
-    font-family: var(--lk-font-family);
+    font-family: var(--lk-font-family-base);
     font-size: var(--lk-font-size-base);
     line-height: 1.6;
   }
@@ -418,10 +418,10 @@
     width: 100%;
     padding: var(--lk-spacing-sm) var(--lk-spacing-md);
     border: 1px solid var(--lk-color-border);
-    border-radius: var(--lk-border-radius-md);
+    border-radius: var(--lk-radius-base);
     background: var(--lk-color-surface);
     color: var(--lk-color-text);
-    font-family: var(--lk-font-family);
+    font-family: var(--lk-font-family-base);
     font-size: var(--lk-font-size-base);
     line-height: 1.5;
     resize: vertical;
@@ -445,10 +445,10 @@
     align-self: flex-start;
     padding: var(--lk-spacing-sm) var(--lk-spacing-lg);
     border: none;
-    border-radius: var(--lk-border-radius-md);
+    border-radius: var(--lk-radius-base);
     background: var(--lk-color-primary);
-    color: var(--lk-color-on-primary);
-    font-family: var(--lk-font-family);
+    color: var(--lk-color-surface);
+    font-family: var(--lk-font-family-base);
     font-size: var(--lk-font-size-base);
     cursor: pointer;
     transition: var(--lk-transition-fast);
@@ -493,7 +493,7 @@
     gap: var(--lk-spacing-sm);
     padding: var(--lk-spacing-md);
     border: 1px solid var(--lk-color-border);
-    border-radius: var(--lk-border-radius-md);
+    border-radius: var(--lk-radius-base);
     background: var(--lk-color-surface);
   }
 

package/dist/{types-DlHmPLbD.d.cts → types-9iS1Vs2I.d.cts}

@@ -5,7 +5,8 @@ import { ActivityData, ActivityResult, LearnerResponse, ItemOutcome, Interaction
  * whether the component may grade, reveal, or submit — the three things a
  * summative exam must take away from the client.
  *
- * - `practice` (default, v1 behaviour): the component owns the attempt. It
+ * - `practice` (default, and the only behaviour before `renderMode` existed):
+ *   the component owns the attempt. It
  *   scores locally on submit, reveals correctness and feedback, and calls
  *   `onComplete` with a full {@link ActivityResult}.
  * - `exam`: the component NEVER scores and NEVER reveals correctness. Submit
@@ -45,12 +46,17 @@ type Renderable<TData> = Omit<TData, 'scoringStrategy'> & {
  */
 type RenderableActivity<TData extends ActivityData = ActivityData> = TData extends unknown ? Renderable<TData> : never;
 /**
- * Sanitiser for author-supplied rich text (`questionHtml`, `passageHtml`,
- * `promptHtml`). The SDK deliberately ships NO sanitiser — that would add a
- * dependency and, worse, a false promise. Rich text is rendered only when you
- * supply this function; without it the component falls back to the plain-text
- * field, which is always escaped. Fail-safe by construction: the SDK never
- * injects HTML it was not explicitly given a sanitiser for.
+ * Sanitiser for author-supplied rich text (`questionHtml`, `promptHtml`, and a
+ * stimulus's `bodyHtml`). The SDK deliberately ships NO sanitiser — that would
+ * add a dependency and, worse, a false promise. Rich text is rendered only when
+ * you supply this function; without it the component falls back to the
+ * plain-text field, which is always escaped. Fail-safe by construction: the SDK
+ * never injects HTML it was not explicitly given a sanitiser for.
+ *
+ * `FillInTheBlanks.passageHtml` is the one exception, and is **never**
+ * rendered: the passage hosts the answer inputs, so it cannot be split at the
+ * `{{blank}}` placeholders without voiding the sanitiser. The plain `passage`
+ * is always used, and passing `passageHtml` warns in development.
  */
 type HtmlSanitizer = (html: string) => string;
 /**
@@ -60,7 +66,8 @@ type HtmlSanitizer = (html: string) => string;
  * Controlled / uncontrolled follows the React convention: pass `value` +
  * `onChange` to own the learner's answer (restore an in-progress attempt,
  * autosave a delta, drive a review); pass `defaultValue` to seed an
- * uncontrolled component; pass neither for the v1 behaviour.
+ * uncontrolled component; pass neither to keep the pre-2.1.0 behaviour, where
+ * the component owns the answer outright.
  */
 interface ActivityProps<TData extends ActivityData = ActivityData> {
     /** Activity content. Accepts a `redact()` projection in `exam` mode. */
@@ -126,8 +133,13 @@ interface ActivityProps<TData extends ActivityData = ActivityData> {
  *
  * Safe because `exam` mode reads only public fields; the answer-key fields the
  * type claims are exactly the ones the component is forbidden to touch there.
- * A future release will derive per-type redacted interfaces so this becomes
- * unnecessary.
+ *
+ * Per-type redacted interfaces (`RedactedMultipleChoiceData`, …) ship from
+ * lk-core since 0.6.0, but they are not yet *assignable* to `data`:
+ * {@link Renderable} widens `scoringStrategy` and leaves nested answer-key
+ * fields (`options[].isCorrect`, `blanks[].acceptedAnswers`) required, so a
+ * real redacted payload still needs this bridge. Closing that gap is tracked
+ * in the roadmap.
  */
 declare function asRenderable<TData extends ActivityData>(redacted: RedactedActivityData): Renderable<TData>;
 /**
@@ -152,9 +164,13 @@ declare function asRenderable<TData extends ActivityData>(redacted: RedactedActi
  * ```
  *
  * Pass `renderMode="exam"` (or `"review"`). Redacted data has no answer key,
- * and the default `practice` mode grades locally — the built-in components
- * throw at render rather than fail at submit time, so a mis-wired exam item is
- * loud, not silent.
+ * and the default `practice` mode grades locally — so `<MultipleChoice>` and
+ * `<FillInTheBlanks>` throw at render rather than fail at submit time.
+ *
+ * `<WrittenResponse>` is the exception: it never grades on the client and has
+ * no such guard, so a redacted essay renders and stays answerable in
+ * `practice`. A mis-wired essay item is therefore SILENT — set `renderMode`
+ * explicitly rather than relying on the throw.
  */
 declare function asRenderableSequence(entries: readonly (RedactedActivityData | RedactedItemGroupData)[]): readonly SequenceEntry<RenderableActivity>[];
 /** Structural shape of a `redactItemGroup()` projection, as it arrives from a server. */

package/dist/{types-DlHmPLbD.d.ts → types-9iS1Vs2I.d.ts}

@@ -5,7 +5,8 @@ import { ActivityData, ActivityResult, LearnerResponse, ItemOutcome, Interaction
  * whether the component may grade, reveal, or submit — the three things a
  * summative exam must take away from the client.
  *
- * - `practice` (default, v1 behaviour): the component owns the attempt. It
+ * - `practice` (default, and the only behaviour before `renderMode` existed):
+ *   the component owns the attempt. It
  *   scores locally on submit, reveals correctness and feedback, and calls
  *   `onComplete` with a full {@link ActivityResult}.
  * - `exam`: the component NEVER scores and NEVER reveals correctness. Submit
@@ -45,12 +46,17 @@ type Renderable<TData> = Omit<TData, 'scoringStrategy'> & {
  */
 type RenderableActivity<TData extends ActivityData = ActivityData> = TData extends unknown ? Renderable<TData> : never;
 /**
- * Sanitiser for author-supplied rich text (`questionHtml`, `passageHtml`,
- * `promptHtml`). The SDK deliberately ships NO sanitiser — that would add a
- * dependency and, worse, a false promise. Rich text is rendered only when you
- * supply this function; without it the component falls back to the plain-text
- * field, which is always escaped. Fail-safe by construction: the SDK never
- * injects HTML it was not explicitly given a sanitiser for.
+ * Sanitiser for author-supplied rich text (`questionHtml`, `promptHtml`, and a
+ * stimulus's `bodyHtml`). The SDK deliberately ships NO sanitiser — that would
+ * add a dependency and, worse, a false promise. Rich text is rendered only when
+ * you supply this function; without it the component falls back to the
+ * plain-text field, which is always escaped. Fail-safe by construction: the SDK
+ * never injects HTML it was not explicitly given a sanitiser for.
+ *
+ * `FillInTheBlanks.passageHtml` is the one exception, and is **never**
+ * rendered: the passage hosts the answer inputs, so it cannot be split at the
+ * `{{blank}}` placeholders without voiding the sanitiser. The plain `passage`
+ * is always used, and passing `passageHtml` warns in development.
  */
 type HtmlSanitizer = (html: string) => string;
 /**
@@ -60,7 +66,8 @@ type HtmlSanitizer = (html: string) => string;
  * Controlled / uncontrolled follows the React convention: pass `value` +
  * `onChange` to own the learner's answer (restore an in-progress attempt,
  * autosave a delta, drive a review); pass `defaultValue` to seed an
- * uncontrolled component; pass neither for the v1 behaviour.
+ * uncontrolled component; pass neither to keep the pre-2.1.0 behaviour, where
+ * the component owns the answer outright.
  */
 interface ActivityProps<TData extends ActivityData = ActivityData> {
     /** Activity content. Accepts a `redact()` projection in `exam` mode. */
@@ -126,8 +133,13 @@ interface ActivityProps<TData extends ActivityData = ActivityData> {
  *
  * Safe because `exam` mode reads only public fields; the answer-key fields the
  * type claims are exactly the ones the component is forbidden to touch there.
- * A future release will derive per-type redacted interfaces so this becomes
- * unnecessary.
+ *
+ * Per-type redacted interfaces (`RedactedMultipleChoiceData`, …) ship from
+ * lk-core since 0.6.0, but they are not yet *assignable* to `data`:
+ * {@link Renderable} widens `scoringStrategy` and leaves nested answer-key
+ * fields (`options[].isCorrect`, `blanks[].acceptedAnswers`) required, so a
+ * real redacted payload still needs this bridge. Closing that gap is tracked
+ * in the roadmap.
  */
 declare function asRenderable<TData extends ActivityData>(redacted: RedactedActivityData): Renderable<TData>;
 /**
@@ -152,9 +164,13 @@ declare function asRenderable<TData extends ActivityData>(redacted: RedactedActi
  * ```
  *
  * Pass `renderMode="exam"` (or `"review"`). Redacted data has no answer key,
- * and the default `practice` mode grades locally — the built-in components
- * throw at render rather than fail at submit time, so a mis-wired exam item is
- * loud, not silent.
+ * and the default `practice` mode grades locally — so `<MultipleChoice>` and
+ * `<FillInTheBlanks>` throw at render rather than fail at submit time.
+ *
+ * `<WrittenResponse>` is the exception: it never grades on the client and has
+ * no such guard, so a redacted essay renders and stays answerable in
+ * `practice`. A mis-wired essay item is therefore SILENT — set `renderMode`
+ * explicitly rather than relying on the throw.
  */
 declare function asRenderableSequence(entries: readonly (RedactedActivityData | RedactedItemGroupData)[]): readonly SequenceEntry<RenderableActivity>[];
 /** Structural shape of a `redactItemGroup()` projection, as it arrives from a server. */