@superbuilders/incept-renderer 0.1.8 → 0.1.12

package/README.md

@@ -12,6 +12,7 @@ A secure, server-driven QTI 3.0 assessment renderer for React/Next.js applicatio
   - [Server Functions](#server-functions)
   - [Client Components](#client-components)
   - [Types](#types)
+- [Rendering Stimuli](#rendering-stimuli)
 - [Theming](#theming)
 - [Complete Examples](#complete-examples)
 - [Supported Interactions](#supported-interactions)
@@ -317,6 +318,29 @@ const result = await validateResponsesSecure(qtiXmlString, {
 }
 ```
 
+#### `parseAssessmentStimulusXml(xml: string)`
+
+Parses QTI Assessment Stimulus XML (reading materials, passages).
+
+```tsx
+import { parseAssessmentStimulusXml } from "@superbuilders/incept-renderer"
+
+const stimulus = parseAssessmentStimulusXml(stimulusXmlString)
+```
+
+**Parameters:**
+- `xml` (string) - Raw QTI 3.0 Assessment Stimulus XML string
+
+**Returns:**
+```tsx
+{
+  identifier: string   // Unique identifier from the XML
+  title: string        // Human-readable title
+  xmlLang: string      // Language code (e.g., "en")
+  bodyHtml: string     // Sanitized HTML content ready for rendering
+}
+```
+
 ---
 
 ### Client Components
@@ -357,6 +381,26 @@ import { QTIRenderer } from "@superbuilders/incept-renderer"
 | `responseFeedback` | `Record<string, { isCorrect: boolean; messageHtml?: string }>` | ❌ | Per-response feedback messages |
 | `theme` | `"duolingo" \| "neobrutalist" \| string` | ❌ | Visual theme (default: `"duolingo"`) |
 
+#### `<QTIStimulusRenderer />`
+
+Renders QTI Assessment Stimuli (reading materials, passages).
+
+```tsx
+import { QTIStimulusRenderer } from "@superbuilders/incept-renderer"
+
+<QTIStimulusRenderer
+  stimulus={parsedStimulus}
+  className="my-8"
+/>
+```
+
+**Props:**
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `stimulus` | `AssessmentStimulus` | ✅ | Parsed stimulus from `parseAssessmentStimulusXml` |
+| `className` | `string` | ❌ | Additional CSS classes for the container |
+
 ---
 
 ### Types
@@ -365,12 +409,15 @@ Import from `@superbuilders/incept-renderer`:
 
 ```tsx
 import type {
+  // Assessment Items (questions)
   DisplayItem,
   DisplayBlock,
   DisplayChoice,
   DisplayChoiceInteraction,
   FormShape,
-  ValidateResult
+  ValidateResult,
+  // Assessment Stimuli (reading materials)
+  AssessmentStimulus
 } from "@superbuilders/incept-renderer"
 ```
 
@@ -435,17 +482,191 @@ interface ValidateResult {
 }
 ```
 
+#### `AssessmentStimulus`
+
+```tsx
+interface AssessmentStimulus {
+  identifier: string   // Unique identifier from the XML
+  title: string        // Human-readable title  
+  xmlLang: string      // Language code (e.g., "en", "es")
+  bodyHtml: string     // Sanitized HTML content
+}
+```
+
+---
+
+## Rendering Stimuli
+
+In addition to assessment items (questions), the package supports rendering **Assessment Stimuli** — reading materials, passages, or articles that provide context for questions.
+
+### What are Stimuli?
+
+QTI Assessment Stimuli (`qti-assessment-stimulus`) are standalone content blocks that contain:
+- Reading passages
+- Articles with images
+- Reference materials
+- Any HTML content that accompanies questions
+
+Unlike assessment items, stimuli have no interactions or correct answers — they're purely display content.
+
+### Parsing Stimulus XML
+
+Use `parseAssessmentStimulusXml` to parse stimulus XML:
+
+```tsx
+import { parseAssessmentStimulusXml } from "@superbuilders/incept-renderer"
+
+const stimulusXml = `<?xml version="1.0" encoding="UTF-8"?>
+<qti-assessment-stimulus 
+  xmlns="http://www.imsglobal.org/xsd/imsqtiasi_v3p0"
+  identifier="stimulus-1" 
+  xml:lang="en" 
+  title="Biodiversity and Ecosystem Health">
+  <qti-stimulus-body>
+    <h2>Biodiversity and ecosystem health</h2>
+    <p><strong>Biodiversity</strong> is the variety of species in an ecosystem.</p>
+    <figure>
+      <img src="coral-reef.jpg" alt="A coral reef" />
+      <figcaption>Coral reef ecosystems have high biodiversity.</figcaption>
+    </figure>
+  </qti-stimulus-body>
+</qti-assessment-stimulus>`
+
+const stimulus = parseAssessmentStimulusXml(stimulusXml)
+// Returns: { identifier, title, xmlLang, bodyHtml }
+```
+
+### Rendering Stimuli
+
+Use the `QTIStimulusRenderer` component to render parsed stimuli:
+
+```tsx
+import { QTIStimulusRenderer, parseAssessmentStimulusXml } from "@superbuilders/incept-renderer"
+
+function ReadingPassage({ xml }: { xml: string }) {
+  const stimulus = parseAssessmentStimulusXml(xml)
+  
+  return (
+    <QTIStimulusRenderer 
+      stimulus={stimulus} 
+      className="my-8"
+    />
+  )
+}
+```
+
+### Server Action Pattern
+
+For Next.js apps, create a server action to parse stimuli:
+
+```tsx
+// lib/qti-actions.ts
+"use server"
+
+import { parseAssessmentStimulusXml } from "@superbuilders/incept-renderer"
+
+export async function parseStimulus(xml: string) {
+  return parseAssessmentStimulusXml(xml)
+}
+```
+
+```tsx
+// app/reading/[id]/page.tsx
+import { parseStimulus } from "@/lib/qti-actions"
+import { QTIStimulusRenderer } from "@superbuilders/incept-renderer"
+
+export default async function ReadingPage({ params }: { params: Promise<{ id: string }> }) {
+  const { id } = await params
+  const xml = await fetchStimulusXml(id) // Your data fetching
+  const stimulus = await parseStimulus(xml)
+  
+  return <QTIStimulusRenderer stimulus={stimulus} />
+}
+```
+
+### Stimulus with Questions
+
+A common pattern is showing a stimulus alongside related questions:
+
+```tsx
+import { QTIStimulusRenderer, QTIRenderer } from "@superbuilders/incept-renderer"
+
+function QuestionWithPassage({ stimulus, item, ...props }) {
+  return (
+    <div className="grid grid-cols-2 gap-8">
+      {/* Reading passage on the left */}
+      <div className="overflow-y-auto max-h-[80vh]">
+        <QTIStimulusRenderer stimulus={stimulus} />
+      </div>
+      
+      {/* Question on the right */}
+      <div>
+        <QTIRenderer item={item} {...props} />
+      </div>
+    </div>
+  )
+}
+```
+
+### AssessmentStimulus Type
+
+```tsx
+interface AssessmentStimulus {
+  identifier: string    // Unique ID from the XML
+  title: string         // Human-readable title
+  xmlLang: string       // Language code (e.g., "en")
+  bodyHtml: string      // Sanitized HTML content
+}
+```
+
+### Supported Content
+
+The stimulus renderer supports:
+- **Headings** (`h1`–`h6`)
+- **Text formatting** (`p`, `strong`, `em`, `b`, `i`, `u`, `sub`, `sup`)
+- **Lists** (`ul`, `ol`, `li`)
+- **Images** (`img`, `figure`, `figcaption`)
+- **Tables** (`table`, `thead`, `tbody`, `tr`, `th`, `td`)
+- **Links** (`a`)
+- **MathML** (mathematical expressions)
+- **Collapsible sections** (`details`, `summary`)
+- **Semantic elements** (`article`, `section`, `blockquote`, `cite`)
+
+All content is sanitized to prevent XSS attacks while preserving safe HTML structure.
+
 ---
 
 ## Theming
 
-The package includes two built-in themes and supports custom themes via CSS variables.
+The package includes two built-in themes and supports custom themes via CSS variables. **You are not required to use the built-in styles** — you can fully customize the appearance to match your application's design system.
+
+### Required CSS Imports
+
+Import the base theme CSS in your app's root layout or global styles:
+
+```tsx
+// In your layout.tsx or globals.css
+import "@superbuilders/incept-renderer/styles/themes.css"
+```
 
 ### Built-in Themes
 
 #### Duolingo (Default)
 
-Clean, friendly design inspired by Duolingo's learning interface.
+Clean, friendly design inspired by Duolingo's learning interface with a vibrant color palette.
+
+**For the complete Duolingo experience**, import the Duolingo theme CSS which includes:
+- Full Duolingo color palette (owl green, macaw blue, cardinal red, etc.)
+- Rounded square choice indicators (A, B, C, D)
+- Filled checkboxes with inset gap effect
+- HTML content styling (lists, typography)
+- Dark mode support
+
+```tsx
+// In your layout.tsx or globals.css
+import "@superbuilders/incept-renderer/styles/themes.css"
+import "@superbuilders/incept-renderer/styles/duolingo.css"  // Full Duolingo styling
+```
 
 ```tsx
 <QTIRenderer theme="duolingo" ... />
@@ -461,19 +682,200 @@ Bold, high-contrast design with thick borders and sharp shadows.
 
 ### Custom Themes
 
-Create your own theme by overriding CSS variables:
+Create your own theme by defining CSS variables for `[data-qti-theme="your-theme-name"]` in your stylesheet, then pass that theme name to the `QTIRenderer` component.
+
+```tsx
+<QTIRenderer theme="my-custom-theme" ... />
+```
+
+### CSS Variables Reference
+
+Below is the **complete list of CSS variables** you can override when creating a custom theme. All variables are optional — any variable you don't define will fall back to the default value.
+
+#### Container Variables
+
+Controls the main question container/card appearance.
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `--qti-container-bg` | Background color of the container | `var(--background, #ffffff)` |
+| `--qti-container-border` | Border color of the container | `var(--border, #e5e5e5)` |
+| `--qti-container-border-width` | Border thickness | `2px` |
+| `--qti-container-radius` | Border radius (rounded corners) | `var(--radius, 0.5rem)` |
+| `--qti-container-shadow` | Box shadow | `none` |
+
+#### Typography Variables
+
+Controls fonts and text styling throughout the renderer.
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `--qti-font-family` | Font family for all QTI text | `inherit` |
+| `--qti-font-weight` | Base font weight | `500` |
+| `--qti-tracking` | Letter spacing | `normal` |
+
+#### Choice Variables
+
+Controls the appearance of answer choices (radio buttons, checkboxes).
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `--qti-choice-bg` | Default background of choices | `var(--background, #ffffff)` |
+| `--qti-choice-border` | Default border color of choices | `var(--accent, #f4f4f5)` |
+| `--qti-choice-hover-bg` | Background on hover | `var(--muted, #f4f4f5)` |
+| `--qti-choice-selected-bg` | Background when selected | `oklch(0.9 0.1 220 / 0.3)` |
+| `--qti-choice-selected-border` | Border when selected | `oklch(0.6 0.2 250)` |
+| `--qti-choice-correct-bg` | Background for correct answers | `oklch(0.9 0.15 140 / 0.3)` |
+| `--qti-choice-correct-border` | Border for correct answers | `#22c55e` |
+| `--qti-choice-incorrect-bg` | Background for incorrect answers | `oklch(0.9 0.1 25 / 0.3)` |
+| `--qti-choice-incorrect-border` | Border for incorrect answers | `#ef4444` |
+
+#### Button Variables
+
+Controls the appearance of buttons (if using the QTI button classes).
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `--qti-button-bg` | Button background color | `var(--primary, #18181b)` |
+| `--qti-button-text` | Button text color | `var(--primary-foreground, #ffffff)` |
+| `--qti-button-border` | Button border color | `var(--primary, #18181b)` |
+| `--qti-button-shadow` | Button box shadow | `none` |
+| `--qti-button-radius` | Button border radius | `var(--radius, 0.5rem)` |
+| `--qti-button-font-weight` | Button font weight | `700` |
+
+#### Feedback Variables
+
+Controls the appearance of feedback messages shown after validation.
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `--qti-feedback-bg` | Feedback container background | `var(--background, #ffffff)` |
+| `--qti-feedback-border` | Feedback container border | `var(--border, #e5e5e5)` |
+| `--qti-feedback-correct-text` | Text color for correct feedback | `#22c55e` |
+| `--qti-feedback-correct-icon-bg` | Icon background for correct | `#22c55e` |
+| `--qti-feedback-incorrect-text` | Text color for incorrect feedback | `#ef4444` |
+| `--qti-feedback-incorrect-icon-bg` | Icon background for incorrect | `#ef4444` |
+
+#### Input Variables (Text Entry, Textarea, Dropdowns)
+
+Controls the appearance of text input fields, textareas, and select/dropdown elements.
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `--qti-input-bg` | Input background color | `var(--background, #ffffff)` |
+| `--qti-input-border` | Input border color | `var(--border, #e5e5e5)` |
+| `--qti-input-border-width` | Input border thickness | `2px` |
+| `--qti-input-radius` | Input border radius | `var(--radius, 0.5rem)` |
+| `--qti-input-shadow` | Input box shadow | `none` |
+| `--qti-input-focus-border` | Border color when focused | `var(--ring, #2563eb)` |
+| `--qti-input-focus-shadow` | Box shadow when focused | `0 0 0 2px rgba(37, 99, 235, 0.2)` |
+| `--qti-input-correct-border` | Border for correct text answers | `#22c55e` |
+| `--qti-input-incorrect-border` | Border for incorrect text answers | `#ef4444` |
+
+#### Choice Indicator Variables (Radio/Checkbox Circles)
+
+Controls the appearance of the radio button and checkbox indicators.
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `--qti-indicator-size` | Size of the indicator | `1.5rem` |
+| `--qti-indicator-bg` | Default background | `var(--background, #ffffff)` |
+| `--qti-indicator-border` | Default border color | `var(--border, #d4d4d8)` |
+| `--qti-indicator-border-width` | Border thickness | `2px` |
+| `--qti-indicator-radius` | Border radius (use `9999px` for circles, `0` for squares) | `9999px` |
+| `--qti-indicator-checked-bg` | Background when checked | `var(--primary, #18181b)` |
+| `--qti-indicator-checked-border` | Border when checked | `var(--primary, #18181b)` |
+| `--qti-indicator-checked-text` | Checkmark/dot color | `var(--primary-foreground, #ffffff)` |
+
+#### Progress Bar Variables
+
+Controls the appearance of progress indicators.
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `--qti-progress-bg` | Progress bar background (empty part) | `var(--muted, #f4f4f5)` |
+| `--qti-progress-fill` | Progress bar fill color | `var(--primary, #18181b)` |
+| `--qti-progress-height` | Height of the progress bar | `0.5rem` |
+| `--qti-progress-radius` | Border radius | `var(--radius, 0.5rem)` |
+| `--qti-progress-border` | Border color | `transparent` |
+| `--qti-progress-border-width` | Border thickness | `0px` |
+
+#### Content Variables (Question Text, Prompts)
+
+Controls the appearance of HTML content (question text, prompts, instructions).
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `--qti-content-font-size` | Font size for content | `1.125rem` |
+| `--qti-content-line-height` | Line height for content | `1.625` |
+| `--qti-content-font-weight` | Font weight for content | `500` |
+
+#### Image Grid Variables
+
+Controls the layout of image-based choice interactions.
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `--qti-grid-gap` | Gap between grid items | `1rem` |
+| `--qti-image-card-min-height` | Minimum height of image cards | `180px` |
+| `--qti-image-card-padding` | Padding inside image cards | `1rem` |
+| `--qti-image-max-height` | Maximum height of images | `160px` |
+
+#### Order Interaction Variables (Drag-and-Drop Sorting)
+
+Controls the appearance of the order interaction container that holds draggable items.
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `--qti-order-container-bg` | Container background | `var(--muted, #f4f4f5)` |
+| `--qti-order-container-border` | Container border color | `transparent` |
+| `--qti-order-container-border-width` | Container border thickness | `2px` |
+| `--qti-order-container-radius` | Container border radius | `0.75rem` |
+| `--qti-order-container-padding` | Container padding | `1rem` |
+| `--qti-order-container-gap` | Gap between drag items | `0.5rem` |
+| `--qti-order-container-correct-bg` | Background when correct | `oklch(0.9 0.15 140 / 0.2)` |
+| `--qti-order-container-correct-border` | Border when correct | `#22c55e` |
+| `--qti-order-container-incorrect-bg` | Background when incorrect | `oklch(0.9 0.1 25 / 0.2)` |
+| `--qti-order-container-incorrect-border` | Border when incorrect | `#ef4444` |
+
+#### Order Item Variables (Drag Tokens)
+
+Controls the appearance of individual draggable items/tokens.
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `--qti-order-item-bg` | Item background | `var(--background, #ffffff)` |
+| `--qti-order-item-border` | Item border color | `var(--border, #e5e5e5)` |
+| `--qti-order-item-border-width` | Item border thickness | `1px` |
+| `--qti-order-item-radius` | Item border radius | `0.5rem` |
+| `--qti-order-item-padding` | Item padding | `1rem` |
+| `--qti-order-item-shadow` | Item box shadow | `0 1px 2px rgba(0, 0, 0, 0.05)` |
+| `--qti-order-item-hover-border` | Border on hover | `oklch(0.6 0.2 250)` |
+| `--qti-order-item-hover-shadow` | Shadow on hover | `0 4px 6px rgba(0, 0, 0, 0.1)` |
+| `--qti-order-item-dragging-border` | Border while dragging | `oklch(0.6 0.2 250)` |
+| `--qti-order-item-dragging-shadow` | Shadow while dragging | `0 8px 16px rgba(0, 0, 0, 0.15)` |
+| `--qti-order-item-handle-color` | Drag handle icon color | `var(--muted-foreground, #71717a)` |
+
+### Complete Custom Theme Example
+
+Here's a complete example defining all variables for a custom theme:
 
 ```css
-/* In your globals.css */
+/* In your globals.css or styles file */
 [data-qti-theme="my-custom-theme"] {
-  /* Container styling */
+  /* ========== Container ========== */
   --qti-container-bg: #ffffff;
   --qti-container-border: #e0e0e0;
   --qti-container-border-width: 1px;
   --qti-container-radius: 12px;
   --qti-container-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
 
-  /* Choice styling */
+  /* ========== Typography ========== */
+  --qti-font-family: "Inter", system-ui, sans-serif;
+  --qti-font-weight: 400;
+  --qti-tracking: normal;
+
+  /* ========== Choices (Radio/Checkbox Cards) ========== */
   --qti-choice-bg: #f8f8f8;
   --qti-choice-border: #d0d0d0;
   --qti-choice-hover-bg: #f0f0f0;
@@ -484,30 +886,151 @@ Create your own theme by overriding CSS variables:
   --qti-choice-incorrect-bg: #ffebee;
   --qti-choice-incorrect-border: #f44336;
 
-  /* Button styling */
+  /* ========== Buttons ========== */
   --qti-button-bg: #2196f3;
   --qti-button-text: #ffffff;
   --qti-button-border: transparent;
   --qti-button-shadow: none;
+  --qti-button-radius: 8px;
+  --qti-button-font-weight: 600;
 
-  /* Typography */
-  --qti-font-family: system-ui, sans-serif;
-  --qti-font-weight: 400;
-
-  /* Feedback styling */
+  /* ========== Feedback Messages ========== */
   --qti-feedback-bg: #ffffff;
   --qti-feedback-border: #e0e0e0;
   --qti-feedback-correct-text: #2e7d32;
+  --qti-feedback-correct-icon-bg: #4caf50;
   --qti-feedback-incorrect-text: #c62828;
+  --qti-feedback-incorrect-icon-bg: #f44336;
+
+  /* ========== Text Inputs / Textareas / Dropdowns ========== */
+  --qti-input-bg: #ffffff;
+  --qti-input-border: #d0d0d0;
+  --qti-input-border-width: 1px;
+  --qti-input-radius: 8px;
+  --qti-input-shadow: none;
+  --qti-input-focus-border: #2196f3;
+  --qti-input-focus-shadow: 0 0 0 3px rgba(33, 150, 243, 0.2);
+  --qti-input-correct-border: #4caf50;
+  --qti-input-incorrect-border: #f44336;
+
+  /* ========== Choice Indicators (Radio/Checkbox Circles) ========== */
+  --qti-indicator-size: 1.5rem;
+  --qti-indicator-bg: #ffffff;
+  --qti-indicator-border: #d0d0d0;
+  --qti-indicator-border-width: 2px;
+  --qti-indicator-radius: 9999px; /* Use 0 for square checkboxes */
+  --qti-indicator-checked-bg: #2196f3;
+  --qti-indicator-checked-border: #2196f3;
+  --qti-indicator-checked-text: #ffffff;
+
+  /* ========== Progress Bar ========== */
+  --qti-progress-bg: #e0e0e0;
+  --qti-progress-fill: #2196f3;
+  --qti-progress-height: 8px;
+  --qti-progress-radius: 4px;
+  --qti-progress-border: transparent;
+  --qti-progress-border-width: 0;
+
+  /* ========== Content (Question Text) ========== */
+  --qti-content-font-size: 1.125rem;
+  --qti-content-line-height: 1.6;
+  --qti-content-font-weight: 400;
+
+  /* ========== Image Grids ========== */
+  --qti-grid-gap: 1rem;
+  --qti-image-card-min-height: 180px;
+  --qti-image-card-padding: 1rem;
+  --qti-image-max-height: 160px;
+
+  /* ========== Order Interaction (Drag-and-Drop Container) ========== */
+  --qti-order-container-bg: #f5f5f5;
+  --qti-order-container-border: #e0e0e0;
+  --qti-order-container-border-width: 1px;
+  --qti-order-container-radius: 12px;
+  --qti-order-container-padding: 1rem;
+  --qti-order-container-gap: 0.75rem;
+  --qti-order-container-correct-bg: rgba(76, 175, 80, 0.15);
+  --qti-order-container-correct-border: #4caf50;
+  --qti-order-container-incorrect-bg: rgba(244, 67, 54, 0.15);
+  --qti-order-container-incorrect-border: #f44336;
+
+  /* ========== Order Items (Drag Tokens) ========== */
+  --qti-order-item-bg: #ffffff;
+  --qti-order-item-border: #e0e0e0;
+  --qti-order-item-border-width: 1px;
+  --qti-order-item-radius: 8px;
+  --qti-order-item-padding: 1rem;
+  --qti-order-item-shadow: 0 2px 4px rgba(0, 0, 0, 0.08);
+  --qti-order-item-hover-border: #2196f3;
+  --qti-order-item-hover-shadow: 0 4px 8px rgba(0, 0, 0, 0.12);
+  --qti-order-item-dragging-border: #2196f3;
+  --qti-order-item-dragging-shadow: 0 8px 16px rgba(0, 0, 0, 0.2);
+  --qti-order-item-handle-color: #9e9e9e;
+}
+
+/* Optional: Dark mode support for your custom theme */
+.dark[data-qti-theme="my-custom-theme"],
+[data-qti-theme="my-custom-theme"] .dark {
+  /* Container */
+  --qti-container-bg: #1a1a1a;
+  --qti-container-border: #333333;
+  
+  /* Choices */
+  --qti-choice-bg: #252525;
+  --qti-choice-border: #444444;
+  --qti-choice-hover-bg: #333333;
+  --qti-choice-selected-bg: rgba(33, 150, 243, 0.2);
+  --qti-choice-selected-border: #2196f3;
+  --qti-choice-correct-bg: rgba(76, 175, 80, 0.2);
+  --qti-choice-incorrect-bg: rgba(244, 67, 54, 0.2);
+  
+  /* Feedback */
+  --qti-feedback-bg: #1a1a1a;
+  --qti-feedback-border: #333333;
+  
+  /* Inputs */
+  --qti-input-bg: #252525;
+  --qti-input-border: #444444;
+  
+  /* Indicators */
+  --qti-indicator-bg: #252525;
+  --qti-indicator-border: #444444;
+  
+  /* Progress */
+  --qti-progress-bg: #333333;
+
+  /* Order Interaction */
+  --qti-order-container-bg: #252525;
+  --qti-order-container-border: #444444;
+  --qti-order-container-correct-bg: rgba(76, 175, 80, 0.2);
+  --qti-order-container-incorrect-bg: rgba(244, 67, 54, 0.2);
+  
+  /* Order Items */
+  --qti-order-item-bg: #1a1a1a;
+  --qti-order-item-border: #444444;
+  --qti-order-item-handle-color: #888888;
 }
 ```
 
-Then use it:
+Then use your custom theme:
 
 ```tsx
 <QTIRenderer theme="my-custom-theme" ... />
 ```
 
+### Partial Overrides
+
+You don't need to define all variables. You can create a theme that only overrides specific values:
+
+```css
+/* Minimal custom theme - only changes colors */
+[data-qti-theme="brand-colors"] {
+  --qti-choice-selected-bg: #your-brand-color-light;
+  --qti-choice-selected-border: #your-brand-color;
+  --qti-button-bg: #your-brand-color;
+}
+```
+
 ---
 
 ## Complete Examples

package/dist/actions/index.d.ts

@@ -1,4 +1,7 @@
-import { g as DisplayItem, F as FormShape, V as ValidateResult } from '../types-B7YRTQKt.js';
+export { a as parseAssessmentStimulusXml } from '../parser-B8n3iHSM.js';
+import { k as DisplayItem, m as FormShape, V as ValidateResult } from '../schema-DKduufCs.js';
+export { a as AssessmentStimulus } from '../schema-DKduufCs.js';
+import 'zod';
 
 declare function buildDisplayModelFromXml(qtiXml: string): {
     itemKey: string;