@superbuilders/incept-renderer 0.1.0 → 0.1.2

package/README.md

@@ -1,114 +1,461 @@
-# @alpha/qti-renderer
+# @superbuilders/incept-renderer
 
-A QTI 3.0 Assessment Renderer for React applications. Parse, validate, and render QTI XML with customizable themes.
+A secure, server-driven QTI 3.0 assessment renderer for React/Next.js applications. Renders interactive questions with built-in validation while keeping correct answers secure on the server.
 
-## Features
+## Table of Contents
 
-- 📝 **QTI 3.0 Support** - Parse and render QTI 3.0 assessment items
-- 🎨 **Themeable** - Built-in Duolingo and Neobrutalist themes, or create your own
-- 🔒 **Secure** - Server-side parsing and validation keeps correct answers hidden
-- ⚛️ **React 18/19** - Works with latest React and Next.js
-- 📦 **Tree-shakeable** - Only import what you need
+- [Installation](#installation)
+- [Core Concepts](#core-concepts)
+- [Quick Start](#quick-start)
+- [Architecture](#architecture)
+- [API Reference](#api-reference)
+  - [Server Functions](#server-functions)
+  - [Client Components](#client-components)
+  - [Types](#types)
+- [Theming](#theming)
+- [Complete Examples](#complete-examples)
+- [Supported Interactions](#supported-interactions)
+- [FAQ](#faq)
+
+---
 
 ## Installation
 
 ```bash
-npm install @alpha/qti-renderer
+npm install @superbuilders/incept-renderer
+# or
+bun add @superbuilders/incept-renderer
 # or
-bun add @alpha/qti-renderer
+yarn add @superbuilders/incept-renderer
 ```
 
-## Quick Start
+### Peer Dependencies
 
-### 1. Parse QTI XML (Server-side)
+This package requires:
+- `react` >= 18.0.0
+- `react-dom` >= 18.0.0
 
-```tsx
-// app/quiz/[id]/page.tsx (Server Component)
-import { parseAssessmentItemXml, validateResponse } from "@alpha/qti-renderer/server"
-import { QTIRenderer } from "@alpha/qti-renderer"
-import "@alpha/qti-renderer/themes/duolingo.css"
+For full functionality with Tailwind CSS theming, ensure your app has Tailwind configured.
+
+---
+
+## Core Concepts
 
-export default async function QuizPage({ params }) {
-  // Fetch and parse QTI XML on the server
-  const xml = await fetchQTIFromDatabase(params.id)
-  const { item } = await parseAssessmentItemXml(xml)
+### Security Model
+
+**Correct answers NEVER leave the server.** This package uses a secure architecture where:
+
+1. **Server parses XML** → Extracts only display data (questions, choices, prompts)
+2. **Client renders UI** → Users interact with questions
+3. **Server validates** → Checks answers against the original XML
+4. **Client shows feedback** → Displays correctness and feedback messages
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  XML Source (your database/API)                                 │
+│  Contains: questions, choices, AND correct answers              │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│  SERVER: buildDisplayModel(xml)                                 │
+│  Extracts: questions, choices, prompts                          │
+│  EXCLUDES: correct answers, response processing rules           │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│  CLIENT: QTIRenderer                                            │
+│  Shows: questions, choices, user can select answers             │
+│  Cannot see: correct answers (never sent to browser)            │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼ User clicks "Check"
+┌─────────────────────────────────────────────────────────────────┐
+│  SERVER: validateResponsesSecure(xml, userResponses)            │
+│  Compares: user answers against correct answers                 │
+│  Returns: isCorrect, feedback HTML, per-choice correctness      │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│  CLIENT: Shows feedback                                         │
+│  Green/red highlights, feedback messages, scores                │
+└─────────────────────────────────────────────────────────────────┘
+```
 
-  // Create server action for validation
-  async function checkAnswer(responses: Record<string, string[]>) {
+---
+
+## Quick Start
+
+### 1. Create the Server Component (page.tsx)
+
+```tsx
+// app/quiz/[id]/page.tsx
+import * as React from "react"
+import { buildDisplayModel, validateResponsesSecure } from "@superbuilders/incept-renderer/actions"
+import { QuizClient } from "./client"
+
+export default function QuizPage({ params }: { params: Promise<{ id: string }> }) {
+  // Fetch your QTI XML and build the display model
+  const displayPromise = params.then(async (p) => {
+    const xml = await getQtiXmlFromYourDatabase(p.id)
+    return buildDisplayModel(xml)
+  })
+
+  // Create a server action for validation
+  async function validateAnswers(responses: Record<string, string | string[]>) {
     "use server"
-    return validateResponse(item, responses)
+    const { id } = await params
+    const xml = await getQtiXmlFromYourDatabase(id)
+    return validateResponsesSecure(xml, responses)
   }
 
-  return <QuizClient item={item} onValidate={checkAnswer} />
+  return (
+    <React.Suspense fallback={<div>Loading question...</div>}>
+      <QuizClient displayPromise={displayPromise} onValidate={validateAnswers} />
+    </React.Suspense>
+  )
+}
+
+// Your function to get QTI XML from wherever you store it
+async function getQtiXmlFromYourDatabase(id: string): Promise<string> {
+  // Examples:
+  // - Database: await db.query.questions.findFirst({ where: eq(id, questionId) })
+  // - REST API: await fetch(`https://api.example.com/questions/${id}`).then(r => r.text())
+  // - File system: await fs.readFile(`./questions/${id}.xml`, 'utf-8')
+  throw new Error("Implement this function")
 }
 ```
 
-### 2. Render and Handle Interactions (Client-side)
+### 2. Create the Client Component (client.tsx)
 
 ```tsx
 // app/quiz/[id]/client.tsx
 "use client"
 
-import { useState } from "react"
-import { QTIRenderer } from "@alpha/qti-renderer"
-import type { AssessmentItem } from "@alpha/qti-renderer"
+import * as React from "react"
+import { QTIRenderer } from "@superbuilders/incept-renderer"
+import type { DisplayItem, FormShape, ValidateResult } from "@superbuilders/incept-renderer"
 
-interface Props {
-  item: AssessmentItem
-  onValidate: (responses: Record<string, string[]>) => Promise<ValidationResult>
+interface QuizClientProps {
+  displayPromise: Promise<{ item: DisplayItem; shape: FormShape; itemKey: string }>
+  onValidate: (responses: Record<string, string | string[]>) => Promise<ValidateResult>
 }
 
-export function QuizClient({ item, onValidate }: Props) {
-  const [responses, setResponses] = useState<Record<string, string[]>>({})
-  const [feedback, setFeedback] = useState(null)
-  const [showFeedback, setShowFeedback] = useState(false)
+export function QuizClient({ displayPromise, onValidate }: QuizClientProps) {
+  // Unwrap the promise from the server
+  const { item, shape, itemKey } = React.use(displayPromise)
+
+  // State management
+  const [responses, setResponses] = React.useState<Record<string, string | string[]>>({})
+  const [result, setResult] = React.useState<ValidateResult | undefined>()
+  const [showFeedback, setShowFeedback] = React.useState(false)
+  const [isChecking, setIsChecking] = React.useState(false)
 
+  // Handle user selecting/changing answers
+  const handleResponseChange = (responseId: string, value: string | string[]) => {
+    setResponses(prev => ({ ...prev, [responseId]: value }))
+  }
+
+  // Handle "Check Answer" click
   const handleCheck = async () => {
-    const result = await onValidate(responses)
-    setFeedback(result)
+    setIsChecking(true)
+    const validation = await onValidate(responses)
+    setResult(validation)
     setShowFeedback(true)
+    setIsChecking(false)
+  }
+
+  // Handle "Try Again" click
+  const handleTryAgain = () => {
+    setShowFeedback(false)
+    setResult(undefined)
   }
 
   return (
-    <div>
+    <div className="max-w-2xl mx-auto p-4">
+      {/* The QTI Renderer */}
       <QTIRenderer
         item={item}
-        theme="duolingo"
         responses={responses}
-        onResponseChange={(id, values) =>
-          setResponses(prev => ({ ...prev, [id]: values }))
-        }
+        onResponseChange={handleResponseChange}
         showFeedback={showFeedback}
-        feedback={feedback}
+        disabled={showFeedback}
+        overallFeedback={result ? {
+          isCorrect: result.overallCorrect,
+          messageHtml: result.feedbackHtml
+        } : undefined}
+        choiceCorrectness={result?.selectedChoicesByResponse}
+        responseFeedback={result?.perResponse}
       />
 
-      <button onClick={handleCheck}>Check Answer</button>
+      {/* Your app's buttons */}
+      <div className="mt-6 flex gap-4">
+        {!showFeedback ? (
+          <button
+            onClick={handleCheck}
+            disabled={isChecking || Object.keys(responses).length === 0}
+            className="bg-green-500 text-white px-6 py-3 rounded-lg font-bold disabled:opacity-50"
+          >
+            {isChecking ? "Checking..." : "Check Answer"}
+          </button>
+        ) : result?.overallCorrect ? (
+          <button
+            onClick={() => window.location.href = "/next-question"}
+            className="bg-green-500 text-white px-6 py-3 rounded-lg font-bold"
+          >
+            Continue →
+          </button>
+        ) : (
+          <button
+            onClick={handleTryAgain}
+            className="bg-blue-500 text-white px-6 py-3 rounded-lg font-bold"
+          >
+            Try Again
+          </button>
+        )}
+      </div>
     </div>
   )
 }
 ```
 
-## Themes
+---
 
-### Built-in Themes
+## Architecture
+
+### File Structure Pattern
+
+```
+app/quiz/[id]/
+├── page.tsx      # Server Component: fetches XML, creates validation action
+└── client.tsx    # Client Component: renders QTIRenderer, manages state
+```
+
+### Data Flow
+
+```
+1. User visits /quiz/123
+       │
+       ▼
+2. page.tsx (Server)
+   - Fetches QTI XML from your data source
+   - Calls buildDisplayModel(xml)
+   - Passes display data to client
+       │
+       ▼
+3. client.tsx (Client)
+   - Renders QTIRenderer with display data
+   - User interacts with choices
+       │
+       ▼
+4. User clicks "Check Answer"
+   - Client calls onValidate(responses)
+   - Server action validates against original XML
+   - Returns { overallCorrect, feedbackHtml, selectedChoicesByResponse }
+       │
+       ▼
+5. Client shows feedback
+   - QTIRenderer shows green/red highlights
+   - Feedback message displayed
+```
+
+---
+
+## API Reference
+
+### Server Functions
+
+Import from `@superbuilders/incept-renderer/actions`:
+
+#### `buildDisplayModel(xml: string)`
+
+Parses QTI XML and extracts display-safe data.
+
+```tsx
+import { buildDisplayModel } from "@superbuilders/incept-renderer/actions"
+
+const { item, shape, itemKey } = await buildDisplayModel(qtiXmlString)
+```
+
+**Parameters:**
+- `xml` (string) - Raw QTI 3.0 XML string
+
+**Returns:**
+```tsx
+{
+  itemKey: string          // Unique identifier for caching
+  item: DisplayItem        // Parsed question data for rendering
+  shape: FormShape         // Schema describing expected response structure
+}
+```
+
+#### `validateResponsesSecure(xml: string, responses: Record<string, string | string[]>)`
+
+Validates user responses against the QTI XML.
+
+```tsx
+import { validateResponsesSecure } from "@superbuilders/incept-renderer/actions"
+
+const result = await validateResponsesSecure(qtiXmlString, {
+  RESPONSE: "choice_A"
+})
+```
+
+**Parameters:**
+- `xml` (string) - Raw QTI 3.0 XML string (same as used for buildDisplayModel)
+- `responses` (Record<string, string | string[]>) - User's selected answers
+
+**Returns:**
+```tsx
+{
+  overallCorrect: boolean   // true if all responses are correct
+  feedbackHtml: string      // Combined HTML feedback message
+  selectedChoicesByResponse: Record<string, Array<{ id: string; isCorrect: boolean }>>
+  perResponse: Record<string, { isCorrect: boolean; messageHtml?: string }>
+}
+```
+
+---
+
+### Client Components
+
+Import from `@superbuilders/incept-renderer`:
+
+#### `<QTIRenderer />`
+
+The main component for rendering QTI questions.
+
+```tsx
+import { QTIRenderer } from "@superbuilders/incept-renderer"
+
+<QTIRenderer
+  item={displayItem}
+  responses={responses}
+  onResponseChange={handleChange}
+  showFeedback={showFeedback}
+  disabled={isDisabled}
+  overallFeedback={feedbackData}
+  choiceCorrectness={correctnessMap}
+  responseFeedback={perResponseFeedback}
+  theme="duolingo"
+/>
+```
+
+**Props:**
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `item` | `DisplayItem` | ✅ | Parsed question data from `buildDisplayModel` |
+| `responses` | `Record<string, string \| string[]>` | ✅ | Current user responses |
+| `onResponseChange` | `(id: string, value: string \| string[]) => void` | ✅ | Called when user selects/changes an answer |
+| `showFeedback` | `boolean` | ❌ | Whether to show correct/incorrect feedback |
+| `disabled` | `boolean` | ❌ | Disable all interactions |
+| `overallFeedback` | `{ isCorrect: boolean; messageHtml?: string }` | ❌ | Overall feedback after validation |
+| `choiceCorrectness` | `Record<string, Array<{ id: string; isCorrect: boolean }>>` | ❌ | Per-choice correctness for highlighting |
+| `responseFeedback` | `Record<string, { isCorrect: boolean; messageHtml?: string }>` | ❌ | Per-response feedback messages |
+| `theme` | `"duolingo" \| "neobrutalist" \| string` | ❌ | Visual theme (default: `"duolingo"`) |
+
+---
+
+### Types
+
+Import from `@superbuilders/incept-renderer`:
+
+```tsx
+import type {
+  DisplayItem,
+  DisplayBlock,
+  DisplayChoice,
+  DisplayChoiceInteraction,
+  FormShape,
+  ValidateResult
+} from "@superbuilders/incept-renderer"
+```
+
+#### `DisplayItem`
+
+```tsx
+interface DisplayItem {
+  identifier: string
+  title: string
+  blocks: DisplayBlock[]
+}
+```
 
-Import the CSS for your chosen theme:
+#### `DisplayBlock`
 
 ```tsx
-// Duolingo-style (rounded, friendly)
-import "@alpha/qti-renderer/themes/duolingo.css"
+type DisplayBlock =
+  | { type: "html"; html: string }
+  | { type: "interaction"; interaction: DisplayChoiceInteraction }
+```
 
-// Neobrutalist (bold, sharp)
-import "@alpha/qti-renderer/themes/neobrutalist.css"
+#### `DisplayChoiceInteraction`
 
-// Base only (minimal styling)
-import "@alpha/qti-renderer/themes/base.css"
+```tsx
+interface DisplayChoiceInteraction {
+  responseIdentifier: string
+  type: "choice"
+  maxChoices: number
+  prompt?: string
+  choices: DisplayChoice[]
+}
 ```
 
-Then set the theme prop:
+#### `DisplayChoice`
+
+```tsx
+interface DisplayChoice {
+  identifier: string
+  contentHtml: string
+}
+```
+
+#### `FormShape`
+
+```tsx
+interface FormShape {
+  responses: Record<string, {
+    cardinality: "single" | "multiple"
+    baseType: string
+  }>
+}
+```
+
+#### `ValidateResult`
+
+```tsx
+interface ValidateResult {
+  overallCorrect: boolean
+  feedbackHtml: string
+  selectedChoicesByResponse: Record<string, Array<{ id: string; isCorrect: boolean }>>
+  perResponse: Record<string, { isCorrect: boolean; messageHtml?: string }>
+}
+```
+
+---
+
+## Theming
+
+The package includes two built-in themes and supports custom themes via CSS variables.
+
+### Built-in Themes
+
+#### Duolingo (Default)
+
+Clean, friendly design inspired by Duolingo's learning interface.
 
 ```tsx
 <QTIRenderer theme="duolingo" ... />
+```
+
+#### Neobrutalist
+
+Bold, high-contrast design with thick borders and sharp shadows.
+
+```tsx
 <QTIRenderer theme="neobrutalist" ... />
 ```
 
@@ -117,54 +464,251 @@ Then set the theme prop:
 Create your own theme by overriding CSS variables:
 
 ```css
-[data-qti-theme="my-theme"] {
-  --qti-container-bg: #1a1a2e;
-  --qti-container-border: #ffffff;
-  --qti-choice-selected-bg: #ff6b6b;
-  /* ... see base.css for all variables */
+/* In your globals.css */
+[data-qti-theme="my-custom-theme"] {
+  /* Container styling */
+  --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 */
+  --qti-choice-bg: #f8f8f8;
+  --qti-choice-border: #d0d0d0;
+  --qti-choice-hover-bg: #f0f0f0;
+  --qti-choice-selected-bg: #e8f4fd;
+  --qti-choice-selected-border: #2196f3;
+  --qti-choice-correct-bg: #e8f5e9;
+  --qti-choice-correct-border: #4caf50;
+  --qti-choice-incorrect-bg: #ffebee;
+  --qti-choice-incorrect-border: #f44336;
+
+  /* Button styling */
+  --qti-button-bg: #2196f3;
+  --qti-button-text: #ffffff;
+  --qti-button-border: transparent;
+  --qti-button-shadow: none;
+
+  /* Typography */
+  --qti-font-family: system-ui, sans-serif;
+  --qti-font-weight: 400;
+
+  /* Feedback styling */
+  --qti-feedback-bg: #ffffff;
+  --qti-feedback-border: #e0e0e0;
+  --qti-feedback-correct-text: #2e7d32;
+  --qti-feedback-incorrect-text: #c62828;
 }
 ```
 
-## API Reference
+Then use it:
 
-### `<QTIRenderer />`
+```tsx
+<QTIRenderer theme="my-custom-theme" ... />
+```
 
-| Prop | Type | Description |
-|------|------|-------------|
-| `item` | `AssessmentItem` | The parsed QTI assessment item |
-| `theme` | `string` | Theme name (default: "duolingo") |
-| `responses` | `Record<string, string[]>` | Current user responses |
-| `onResponseChange` | `(id, values) => void` | Called when user changes response |
-| `showFeedback` | `boolean` | Whether to show feedback |
-| `feedback` | `ResponseFeedback` | Overall feedback data |
-| `disabled` | `boolean` | Disable all interactions |
+---
 
-### `parseAssessmentItemXml(xml)`
+## Complete Examples
 
-Parses QTI XML into an `AssessmentItem`. Server-side only.
+### Example 1: Simple Quiz Page
 
-```ts
-const { success, item, error } = await parseAssessmentItemXml(xml)
+```tsx
+// app/quiz/[id]/page.tsx
+import * as React from "react"
+import { buildDisplayModel, validateResponsesSecure } from "@superbuilders/incept-renderer/actions"
+import { db } from "@/db"
+import { questions } from "@/db/schema"
+import { eq } from "drizzle-orm"
+import { QuizClient } from "./client"
+
+export default function QuizPage({ params }: { params: Promise<{ id: string }> }) {
+  const displayPromise = params.then(async (p) => {
+    const question = await db.query.questions.findFirst({
+      where: eq(questions.id, p.id)
+    })
+    if (!question) throw new Error("Question not found")
+    return buildDisplayModel(question.xml)
+  })
+
+  async function validate(responses: Record<string, string | string[]>) {
+    "use server"
+    const { id } = await params
+    const question = await db.query.questions.findFirst({
+      where: eq(questions.id, id)
+    })
+    if (!question) throw new Error("Question not found")
+    return validateResponsesSecure(question.xml, responses)
+  }
+
+  return (
+    <React.Suspense fallback={<LoadingSkeleton />}>
+      <QuizClient displayPromise={displayPromise} onValidate={validate} />
+    </React.Suspense>
+  )
+}
 ```
 
-### `validateResponse(item, responses)`
+### Example 2: Multi-Question Assessment
 
-Validates user responses against correct answers. Server-side only.
+```tsx
+// app/assessment/[id]/page.tsx
+import * as React from "react"
+import { buildDisplayModel, validateResponsesSecure } from "@superbuilders/incept-renderer/actions"
+import { AssessmentClient } from "./client"
+
+export default function AssessmentPage({ params }: { params: Promise<{ id: string }> }) {
+  // Fetch all questions for this assessment
+  const questionsPromise = params.then(async (p) => {
+    const assessment = await fetchAssessment(p.id)
+    return Promise.all(
+      assessment.questionIds.map(async (qId) => {
+        const xml = await fetchQuestionXml(qId)
+        const display = await buildDisplayModel(xml)
+        return { id: qId, xml, ...display }
+      })
+    )
+  })
+
+  // Generic validator that works for any question
+  async function validateQuestion(questionId: string, responses: Record<string, string | string[]>) {
+    "use server"
+    const xml = await fetchQuestionXml(questionId)
+    return validateResponsesSecure(xml, responses)
+  }
 
-```ts
-const result = await validateResponse(item, responses)
-// { isCorrect, responses, feedbackHtml, score, maxScore }
+  return (
+    <React.Suspense fallback={<div>Loading assessment...</div>}>
+      <AssessmentClient 
+        questionsPromise={questionsPromise} 
+        onValidate={validateQuestion} 
+      />
+    </React.Suspense>
+  )
+}
 ```
 
-## Supported Interaction Types
+### Example 3: With Theming Toggle
+
+```tsx
+// app/quiz/[id]/client.tsx
+"use client"
+
+import * as React from "react"
+import { QTIRenderer } from "@superbuilders/incept-renderer"
+import type { DisplayItem, FormShape, ValidateResult } from "@superbuilders/incept-renderer"
+
+const THEMES = [
+  { value: "duolingo", label: "Duolingo" },
+  { value: "neobrutalist", label: "Neobrutalist" },
+] as const
+
+type Theme = typeof THEMES[number]["value"]
+
+export function QuizClient({ displayPromise, onValidate }: {
+  displayPromise: Promise<{ item: DisplayItem; shape: FormShape; itemKey: string }>
+  onValidate: (r: Record<string, string | string[]>) => Promise<ValidateResult>
+}) {
+  const { item } = React.use(displayPromise)
+  
+  const [responses, setResponses] = React.useState<Record<string, string | string[]>>({})
+  const [result, setResult] = React.useState<ValidateResult | undefined>()
+  const [showFeedback, setShowFeedback] = React.useState(false)
+  const [theme, setTheme] = React.useState<Theme>("duolingo")
+
+  return (
+    <div>
+      {/* Theme Selector */}
+      <div className="mb-4 flex justify-end">
+        <select
+          value={theme}
+          onChange={(e) => setTheme(e.target.value as Theme)}
+          className="border rounded px-2 py-1"
+        >
+          {THEMES.map((t) => (
+            <option key={t.value} value={t.value}>{t.label}</option>
+          ))}
+        </select>
+      </div>
+
+      {/* Question Renderer */}
+      <QTIRenderer
+        item={item}
+        responses={responses}
+        onResponseChange={(id, val) => setResponses(prev => ({ ...prev, [id]: val }))}
+        showFeedback={showFeedback}
+        theme={theme}
+        overallFeedback={result ? {
+          isCorrect: result.overallCorrect,
+          messageHtml: result.feedbackHtml
+        } : undefined}
+        choiceCorrectness={result?.selectedChoicesByResponse}
+      />
+
+      {/* Check Button */}
+      <button
+        onClick={async () => {
+          const validation = await onValidate(responses)
+          setResult(validation)
+          setShowFeedback(true)
+        }}
+        disabled={showFeedback}
+        className="mt-4 bg-blue-500 text-white px-4 py-2 rounded"
+      >
+        Check Answer
+      </button>
+    </div>
+  )
+}
+```
+
+---
+
+## Supported Interactions
+
+| Interaction Type | Support | Description |
+|------------------|---------|-------------|
+| `choiceInteraction` | ✅ Full | Single/multiple choice questions |
+| `inlineChoiceInteraction` | ✅ Full | Dropdown selections within text |
+| `textEntryInteraction` | ✅ Full | Free-text input fields |
+| `orderInteraction` | 🔶 Basic | Drag-and-drop ordering |
+| `matchInteraction` | 🔶 Basic | Matching pairs |
+| `gapMatchInteraction` | 🔶 Basic | Fill-in-the-blank with draggable options |
+
+---
+
+## FAQ
+
+### How do I store QTI XML?
+
+Store it however works best for your app:
+- **Database:** Store as a TEXT/VARCHAR column
+- **File system:** Store as `.xml` files
+- **External API:** Fetch from a QTI content server
+
+The package doesn't care where the XML comes from—it just needs a string.
+
+### Can users cheat by inspecting the browser?
+
+No! Correct answers are **never sent to the browser**. The `buildDisplayModel` function only extracts display data. Validation happens on the server with the original XML.
+
+### How do I add custom styling?
+
+Use the `theme` prop with a custom theme name, then define CSS variables for `[data-qti-theme="your-theme"]` in your stylesheet.
+
+### Can I use this without Next.js?
+
+The package is designed for Next.js server components and server actions. For other frameworks, you'd need to:
+1. Create your own server endpoint for `buildDisplayModel` and `validateResponsesSecure`
+2. Call those endpoints from your client
+
+### How do I handle MathML/LaTeX?
+
+The package preserves MathML in the HTML output. Ensure your app has MathML rendering support (modern browsers handle it natively, or use MathJax/KaTeX for broader support).
 
-- ✅ Choice Interaction (single & multiple)
-- ✅ Inline Choice Interaction (dropdowns)
-- ✅ Text Entry Interaction
-- 🚧 Order Interaction
-- 🚧 Gap Match Interaction
-- 🚧 Match Interaction
+---
 
 ## License
 
-MIT
+MIT © Superbuilders