# Beadkit

Learning primitives for AI-native interfaces — components an LLM can emit mid-stream, rendered natively with xAPI telemetry.
Registry: https://beadkit.dev/r/<name>.json

## Install

- learning-core — Shared card shell and xAPI telemetry. Every learning component depends on this; installing a component pulls it in automatically.
  npx shadcn@latest add https://beadkit.dev/r/learning-core.json
- quiz — Inline concept check with immediate feedback and an xAPI answered statement.
  npx shadcn@latest add https://beadkit.dev/r/quiz.json
- flashcard — Two-sided card with an xAPI experienced statement on first reveal.
  npx shadcn@latest add https://beadkit.dev/r/flashcard.json
- sequence — Shuffled steps the learner reorders, with keyboard controls and an xAPI answered statement carrying the submitted order.
  npx shadcn@latest add https://beadkit.dev/r/sequence.json
- mastery — Per-skill mastery bars plus a learner self-rating, emitting an xAPI rated statement.
  npx shadcn@latest add https://beadkit.dev/r/mastery.json
- learning-stream — Parses <LEARNING_COMPONENT> payloads out of streaming model output and hydrates them inline. Pulls in every component it can render.
  npx shadcn@latest add https://beadkit.dev/r/learning-stream.json

## Source

### components/learning/LearningCard.tsx

```tsx
import type { ReactNode } from "react";
import { cn } from "@/lib/utils";

export interface LearningCardProps {
  /** Eyebrow label, e.g. "Concept check". Rendered uppercase. */
  label: string;
  /** Component type, exposed for the parser and the QA harness to find. */
  type: string;
  children: ReactNode;
  className?: string;
}

/**
 * Shared shell for every learning component: surface, eyebrow, sizing. Keeping
 * the chrome here means a new component only writes its own interaction, and a
 * change to the surface applies to all of them at once.
 */
export function LearningCard({ label, type, children, className }: LearningCardProps) {
  return (
    <div
      data-learning-type={type}
      className={cn(
        "bg-card text-card-foreground w-full max-w-md rounded-xl border p-4 shadow-sm",
        className
      )}
    >
      <div className="bg-primary text-primary-foreground mb-3 w-max rounded px-2 py-0.5 text-[10px] font-bold uppercase tracking-wider">
        {label}
      </div>
      {children}
    </div>
  );
}
```

### components/learning/ComponentBoundary.tsx

```tsx
"use client";
import { Component, type ReactNode } from "react";

interface Props {
  children: ReactNode;
  fallback: ReactNode;
}

/**
 * Isolates one learning component's render from the rest of the page.
 *
 * Validation in the registry rejects malformed payloads, but it cannot prove a
 * component will not throw — a deep field can still be the wrong shape, and a
 * host app may pass its own props. Without a boundary, one bad activity in a
 * streamed lesson unmounts the entire host tree. The cost of being wrong here
 * is somebody else's app going blank, so the boundary is not optional.
 *
 * Class component because React exposes error catching only via lifecycle.
 */
export class ComponentBoundary extends Component<Props, { failed: boolean }> {
  state = { failed: false };

  static getDerivedStateFromError() {
    return { failed: true };
  }

  componentDidCatch(error: unknown) {
    // The host app owns real reporting; surfacing it beats swallowing it.
    console.error("Learning component failed to render", error);
  }

  render() {
    return this.state.failed ? this.props.fallback : this.props.children;
  }
}
```

### components/learning/xapi.ts

```tsx
import { useCallback, useRef } from "react";

/** Verbs we emit. Add here as components need them. */
const VERB_IDS = {
  answered: "http://adlnet.gov/expapi/verbs/answered",
  experienced: "http://adlnet.gov/expapi/verbs/experienced",
  // Not an ADL verb — self-assessment has no ADL equivalent, and the registered
  // tincanapi verb is what an LRS will already recognise for it.
  rated: "http://id.tincanapi.com/verb/rated",
} as const;

export type XApiVerb = keyof typeof VERB_IDS;

export interface XApiStatement {
  verb: { id: string; display: { "en-US": string } };
  object: { id: string; definition: { name: { "en-US": string } } };
  result: {
    response?: string;
    success?: boolean;
    completion: boolean;
    duration: string;
  };
}

export interface StatementInput {
  verb: XApiVerb;
  activityId: string;
  /** Human-readable activity name, e.g. the quiz prompt or flashcard front. */
  name: string;
  durationMs: number;
  response?: string;
  success?: boolean;
}

export function buildStatement({
  verb,
  activityId,
  name,
  durationMs,
  response,
  success,
}: StatementInput): XApiStatement {
  const seconds = Math.max(0, Math.round(durationMs / 1000));
  return {
    verb: { id: VERB_IDS[verb], display: { "en-US": verb } },
    object: {
      id: `http://beadkit.dev/activities/${activityId}`,
      definition: { name: { "en-US": name } },
    },
    result: {
      // Omitted rather than sent as null: an LRS treats a present-but-null
      // `success` as a scored attempt, which a flashcard view is not.
      ...(response !== undefined && { response }),
      ...(success !== undefined && { success }),
      completion: true,
      duration: `PT${seconds}S`,
    },
  };
}

/**
 * Times the learner's engagement and emits an xAPI statement. Every learning
 * component needs the same start-clock + emit pair, so it lives here rather
 * than being re-implemented per component.
 */
export function useTelemetry(
  activityId: string,
  name: string,
  onTrackTelemetry?: (statement: XApiStatement) => void
) {
  // Set on first render, not on mount, so time spent before hydration counts.
  const startedAt = useRef(Date.now());
  return useCallback(
    (verb: XApiVerb, extra: Pick<StatementInput, "response" | "success"> = {}) => {
      onTrackTelemetry?.(
        buildStatement({
          verb,
          activityId,
          name,
          durationMs: Date.now() - startedAt.current,
          ...extra,
        })
      );
    },
    [activityId, name, onTrackTelemetry]
  );
}

// Self-check: npx tsx components/learning/xapi.ts
if (process.argv[1]?.endsWith("xapi.ts")) {
  const quiz = buildStatement({
    verb: "answered",
    activityId: "quiz-1",
    name: "HTTP Idempotency Check",
    durationMs: 14400,
    response: "B",
    success: true,
  });
  console.assert(quiz.object.id === "http://beadkit.dev/activities/quiz-1", "object id");
  console.assert(quiz.verb.id.endsWith("/answered"), "verb id");
  console.assert(quiz.result.duration === "PT14S", "duration rounds to seconds");
  console.assert(quiz.result.success === true && quiz.result.response === "B", "result fields");

  const card = buildStatement({
    verb: "experienced",
    activityId: "card-1",
    name: "Idempotent",
    durationMs: 400,
  });
  console.assert(!("success" in card.result), "success omitted when not scored");
  console.assert(!("response" in card.result), "response omitted when not scored");
  console.assert(card.result.duration === "PT0S", "sub-second rounds to PT0S");
  console.assert(card.verb.id.endsWith("/experienced"), "experienced verb id");

  // Self-assessment carries a response but no success: the learner's own rating
  // is not a scored attempt, and an LRS reads `success` as one.
  const rating = buildStatement({
    verb: "rated",
    activityId: "mastery-1",
    name: "REST fundamentals",
    durationMs: 9000,
    response: "solid",
  });
  console.assert(rating.verb.id === "http://id.tincanapi.com/verb/rated", "rated verb id");
  console.assert(rating.result.response === "solid", "rating response");
  console.assert(!("success" in rating.result), "self-rating is not scored");

  console.log("xapi self-check passed");
}
```

### components/learning/QuizBlock.tsx

```tsx
"use client";
import { useState } from "react";
import { LearningCard } from "./LearningCard";
import { useTelemetry, type XApiStatement } from "./xapi";

export interface QuizOption {
  id: string;
  text: string;
  valid: boolean;
  feedback: string;
}

export interface QuizBlockProps {
  activityId: string;
  prompt: string;
  options: QuizOption[];
  onTrackTelemetry?: (statement: XApiStatement) => void;
}

export function QuizBlock({ activityId, prompt, options, onTrackTelemetry }: QuizBlockProps) {
  const [selected, setSelected] = useState<string | null>(null);
  const [submitted, setSubmitted] = useState(false);
  const track = useTelemetry(activityId, prompt, onTrackTelemetry);

  const chosen = options.find((o) => o.id === selected);

  const handleSubmit = () => {
    if (!chosen || submitted) return;
    setSubmitted(true);
    track("answered", { response: chosen.id, success: chosen.valid });
  };

  return (
    <LearningCard label="Concept check" type="quiz">
      <p id={`${activityId}-prompt`} className="mb-3 text-sm font-semibold">
        {prompt}
      </p>
      <fieldset
        role="radiogroup"
        aria-labelledby={`${activityId}-prompt`}
        disabled={submitted}
        className="space-y-2"
      >
        {options.map((opt) => {
          const isSelected = selected === opt.id;
          return (
            <label
              key={opt.id}
              className={`has-[:focus-visible]:ring-ring block w-full cursor-pointer rounded-lg border p-3 text-left text-xs transition-all has-[:focus-visible]:ring-2 has-[:focus-visible]:ring-offset-1 ${
                isSelected
                  ? "border-primary bg-primary/5 font-medium"
                  : "hover:border-muted-foreground/40"
              } ${submitted ? "cursor-default opacity-80" : ""}`}
            >
              <input
                type="radio"
                name={`${activityId}-choice`}
                value={opt.id}
                checked={isSelected}
                onChange={() => setSelected(opt.id)}
                className="sr-only"
              />
              <span className="text-muted-foreground mr-1.5 font-mono">{opt.id}.</span>
              {opt.text}
            </label>
          );
        })}
      </fieldset>
      {selected && !submitted && (
        <button
          onClick={handleSubmit}
          className="bg-primary text-primary-foreground hover:bg-primary/90 focus-visible:ring-ring mt-3 w-full rounded-lg py-2 text-xs font-medium transition focus-visible:ring-2 focus-visible:ring-offset-1"
        >
          Submit answer
        </button>
      )}
      <div aria-live="polite">
        {submitted && chosen && (
          <div
            className={`mt-3 rounded-lg border p-3 text-xs ${
              chosen.valid
                ? "border-success/30 bg-success/10"
                : "border-destructive/30 bg-destructive/10"
            }`}
          >
            <span
              className={`mb-1 block font-bold ${
                chosen.valid ? "text-success" : "text-destructive"
              }`}
            >
              {chosen.valid ? "Correct" : "Incorrect"}
            </span>
            {chosen.feedback}
          </div>
        )}
      </div>
    </LearningCard>
  );
}
```

### components/learning/FlashcardBlock.tsx

```tsx
"use client";
import { useState } from "react";
import { LearningCard } from "./LearningCard";
import { useTelemetry, type XApiStatement } from "./xapi";

export interface FlashcardBlockProps {
  activityId: string;
  front: string;
  back: string;
  onTrackTelemetry?: (statement: XApiStatement) => void;
}

export function FlashcardBlock({
  activityId,
  front,
  back,
  onTrackTelemetry,
}: FlashcardBlockProps) {
  const [revealed, setRevealed] = useState(false);
  const [tracked, setTracked] = useState(false);
  const track = useTelemetry(activityId, front, onTrackTelemetry);

  const flip = () => {
    setRevealed((v) => !v);
    // Only the first reveal is a learning event; flipping back and forth is not
    // repeated engagement and would inflate the LRS record.
    if (!tracked) {
      setTracked(true);
      track("experienced");
    }
  };

  return (
    <LearningCard label="Flashcard" type="flashcard">
      <button
        onClick={flip}
        aria-expanded={revealed}
        className="focus-visible:ring-ring hover:border-muted-foreground/40 flex min-h-24 w-full flex-col items-center justify-center gap-2 rounded-lg border p-4 text-center transition-all focus-visible:ring-2 focus-visible:ring-offset-1"
      >
        <span className="text-muted-foreground font-mono text-[10px] font-bold uppercase tracking-wider">
          {revealed ? "Back" : "Front"}
        </span>
        <span aria-live="polite" className="text-sm font-medium">
          {revealed ? back : front}
        </span>
      </button>
      <p className="text-muted-foreground mt-2 text-center text-[11px]">
        {revealed ? "Click to flip back" : "Click to reveal the answer"}
      </p>
    </LearningCard>
  );
}
```

### components/learning/SequenceBuilder.tsx

```tsx
"use client";
import { useEffect, useRef, useState } from "react";
import { LearningCard } from "./LearningCard";
import { useTelemetry, type XApiStatement } from "./xapi";

export interface SequenceStep {
  id: string;
  text: string;
}

export interface SequenceBuilderProps {
  activityId: string;
  prompt: string;
  /** The correct order. Shown shuffled; the learner reorders back to this. */
  steps: SequenceStep[];
  onTrackTelemetry?: (statement: XApiStatement) => void;
}

/**
 * Deterministic shuffle: same seed, same order, every time.
 *
 * `Math.random()` here would produce one order on the server and another in the
 * browser, which is a hydration mismatch. Seeding from the activity id keeps the
 * function pure, so both sides agree.
 */
function shuffle(steps: SequenceStep[], seed: string): SequenceStep[] {
  let h = 2166136261;
  for (let i = 0; i < seed.length; i++) h = Math.imul(h ^ seed.charCodeAt(i), 16777619);

  const out = [...steps];
  for (let i = out.length - 1; i > 0; i--) {
    h = Math.imul(h ^ (h >>> 15), 2246822507);
    const j = (h >>> 0) % (i + 1);
    [out[i], out[j]] = [out[j], out[i]];
  }
  // A shuffle that lands on the answer hands the learner a solved activity.
  // Rotate rather than reshuffle: one step is enough to break it, and it always
  // terminates.
  return out.every((s, i) => s.id === steps[i].id) ? [...out.slice(1), out[0]] : out;
}

const btnId = (activityId: string, stepId: string, dir: "up" | "down") =>
  `${activityId}-${stepId}-${dir}`;

export function SequenceBuilder({
  activityId,
  prompt,
  steps,
  onTrackTelemetry,
}: SequenceBuilderProps) {
  const [order, setOrder] = useState(() => shuffle(steps, activityId));
  const [submitted, setSubmitted] = useState(false);
  const track = useTelemetry(activityId, prompt, onTrackTelemetry);

  // Reordering re-renders the list under the button that was just clicked, so
  // focus has to be put back by hand or every move drops the keyboard user out
  // of the list.
  const refocus = useRef<string | null>(null);
  useEffect(() => {
    if (!refocus.current) return;
    document.getElementById(refocus.current)?.focus();
    refocus.current = null;
  });

  const move = (from: number, delta: number) => {
    if (submitted) return;
    const to = from + delta;
    const next = [...order];
    [next[from], next[to]] = [next[to], next[from]];
    setOrder(next);
    // The button just clicked may not exist at the item's new position — an
    // item at the top has no "up" — so fall back to the opposite one.
    const up = delta < 0;
    const clickedStillExists = up ? to > 0 : to < next.length - 1;
    refocus.current = btnId(
      activityId,
      next[to].id,
      clickedStillExists ? (up ? "up" : "down") : up ? "down" : "up"
    );
  };

  const correct = order.every((s, i) => s.id === steps[i].id);

  const handleSubmit = () => {
    if (submitted) return;
    setSubmitted(true);
    track("answered", { response: order.map((s) => s.id).join(","), success: correct });
  };

  return (
    <LearningCard label="Put it in order" type="sequence">
      <p id={`${activityId}-prompt`} className="mb-3 text-sm font-semibold">
        {prompt}
      </p>

      <ol aria-labelledby={`${activityId}-prompt`} className="space-y-2">
        {order.map((step, i) => (
          <li
            key={step.id}
            className="flex items-center gap-2 rounded-lg border p-3 text-xs transition-all"
          >
            <span className="text-muted-foreground w-4 shrink-0 font-mono">{i + 1}</span>
            <span className="flex-1">{step.text}</span>
            {!submitted && (
              // Rendered only when the move is possible. A dimmed disabled
              // arrow would sit below 4.5:1 and fail the contrast check, and an
              // invisible one still takes tab focus.
              <span className="flex shrink-0 gap-0.5">
                <span className="w-6">
                  {i > 0 && (
                    <button
                      id={btnId(activityId, step.id, "up")}
                      onClick={() => move(i, -1)}
                      aria-label={`Move “${step.text}” up`}
                      className="text-muted-foreground hover:text-foreground focus-visible:ring-ring h-6 w-6 rounded transition focus-visible:ring-2"
                    >
                      ↑
                    </button>
                  )}
                </span>
                <span className="w-6">
                  {i < order.length - 1 && (
                    <button
                      id={btnId(activityId, step.id, "down")}
                      onClick={() => move(i, 1)}
                      aria-label={`Move “${step.text}” down`}
                      className="text-muted-foreground hover:text-foreground focus-visible:ring-ring h-6 w-6 rounded transition focus-visible:ring-2"
                    >
                      ↓
                    </button>
                  )}
                </span>
              </span>
            )}
          </li>
        ))}
      </ol>

      {!submitted && (
        <button
          onClick={handleSubmit}
          className="bg-primary text-primary-foreground hover:bg-primary/90 focus-visible:ring-ring mt-3 w-full rounded-lg py-2 text-xs font-medium transition focus-visible:ring-2 focus-visible:ring-offset-1"
        >
          Check order
        </button>
      )}

      <div aria-live="polite">
        {submitted && (
          <div
            className={`mt-3 rounded-lg border p-3 text-xs ${
              correct ? "border-success/30 bg-success/10" : "border-destructive/30 bg-destructive/10"
            }`}
          >
            <span
              className={`mb-1 block font-bold ${correct ? "text-success" : "text-destructive"}`}
            >
              {correct ? "Correct" : "Not quite"}
            </span>
            {correct
              ? "That is the right sequence."
              : `The right order is: ${steps.map((s) => s.text).join(" → ")}`}
          </div>
        )}
      </div>
    </LearningCard>
  );
}
```

### components/learning/MasteryMeter.tsx

```tsx
"use client";
import { useState } from "react";
import { LearningCard } from "./LearningCard";
import { useTelemetry, type XApiStatement } from "./xapi";

export interface MasterySkill {
  id: string;
  label: string;
  /** The model's assessment of the learner, 0 to 1. */
  level: number;
}

export interface MasteryMeterProps {
  activityId: string;
  title: string;
  skills: MasterySkill[];
  onTrackTelemetry?: (statement: XApiStatement) => void;
}

const RATINGS = [
  { id: "shaky", label: "Still shaky" },
  { id: "getting-there", label: "Getting there" },
  { id: "solid", label: "Solid" },
];

/** Segments per bar. Discrete reads as a level; a continuous fill reads as a
 *  loading state, which is the wrong idea for a mastery figure. */
const SEGMENTS = 5;

export function MasteryMeter({
  activityId,
  title,
  skills,
  onTrackTelemetry,
}: MasteryMeterProps) {
  const [rated, setRated] = useState<string | null>(null);
  const track = useTelemetry(activityId, title, onTrackTelemetry);

  const overall = skills.reduce((sum, s) => sum + s.level, 0) / skills.length;

  const rate = (id: string) => {
    if (rated) return;
    setRated(id);
    // No `success`: a self-rating is the learner's own read, not a scored
    // attempt, and an LRS treats a present `success` as one.
    track("rated", { response: id });
  };

  return (
    <LearningCard label="Where you are" type="mastery">
      <div className="mb-3 flex items-baseline justify-between gap-3">
        <p className="text-sm font-semibold">{title}</p>
        <span className="font-mono text-sm font-semibold">{Math.round(overall * 100)}%</span>
      </div>

      <ul className="space-y-2.5">
        {skills.map((skill) => {
          const filled = Math.round(skill.level * SEGMENTS);
          return (
            <li key={skill.id}>
              <div className="mb-1 flex items-baseline justify-between gap-3">
                <span className="text-xs">{skill.label}</span>
                <span className="text-muted-foreground font-mono text-[11px]">
                  {Math.round(skill.level * 100)}%
                </span>
              </div>
              <div
                className="flex gap-1"
                role="meter"
                aria-valuenow={filled}
                aria-valuemin={0}
                aria-valuemax={SEGMENTS}
                aria-label={skill.label}
              >
                {Array.from({ length: SEGMENTS }, (_, i) => (
                  <span
                    key={i}
                    // `bg-muted` is identical to `bg-card` in the dark palette,
                    // so the empty track has to come from a foreground alpha to
                    // stay visible in both modes.
                    className={`h-1.5 flex-1 rounded-full ${
                      i < filled ? "bg-primary" : "bg-muted-foreground/25"
                    }`}
                  />
                ))}
              </div>
            </li>
          );
        })}
      </ul>

      <fieldset className="mt-4" disabled={rated !== null}>
        <legend className="text-muted-foreground mb-2 text-xs">
          How solid does this feel to you?
        </legend>
        <div className="flex gap-1.5">
          {RATINGS.map((r) => (
            <label
              key={r.id}
              className={`has-[:focus-visible]:ring-ring flex-1 cursor-pointer rounded-lg border p-2 text-center text-[11px] transition-all has-[:focus-visible]:ring-2 has-[:focus-visible]:ring-offset-1 ${
                rated === r.id
                  ? "border-primary bg-primary/5 font-medium"
                  : "hover:border-muted-foreground/40"
              } ${rated ? "cursor-default" : ""}`}
            >
              <input
                type="radio"
                name={`${activityId}-rating`}
                value={r.id}
                checked={rated === r.id}
                onChange={() => rate(r.id)}
                className="sr-only"
              />
              {r.label}
            </label>
          ))}
        </div>
      </fieldset>

      <div aria-live="polite">
        {rated && (
          <p className="text-muted-foreground mt-3 text-xs">
            Noted — your tutor will weight the next questions accordingly.
          </p>
        )}
      </div>
    </LearningCard>
  );
}
```

### components/learning/parse.ts

```tsx
import { registry, type LearningType } from "./registry";

const OPEN = "<LEARNING_COMPONENT>";
const CLOSE = "</LEARNING_COMPONENT>";

export type Segment =
  | { kind: "text"; text: string }
  /** Validated payload, ready to render. */
  | { kind: "component"; type: LearningType; data: Record<string, unknown>; activityId: string }
  /** Tag closed but the payload was malformed or of an unknown type. */
  | { kind: "invalid"; activityId: string }
  /** Tag opened and the stream has not closed it yet. */
  | { kind: "pending" };

/**
 * If the text ends mid-tag ("...<LEARNING_COMP"), that fragment is the start of
 * a component, not prose. Without this the raw tag characters flash on screen
 * as the stream arrives.
 */
function trimPartialOpenTag(text: string): string {
  for (let i = OPEN.length - 1; i > 0; i--) {
    if (text.endsWith(OPEN.slice(0, i))) return text.slice(0, -i);
  }
  return text;
}

/** The protocol forbids code fences inside the tags, but models add them anyway. */
function stripFences(raw: string): string {
  return raw
    .replace(/^\s*```(?:json)?\s*/i, "")
    .replace(/\s*```\s*$/, "")
    .trim();
}

function classify(raw: string, activityId: string): Segment {
  let data: unknown;
  try {
    data = JSON.parse(stripFences(raw));
  } catch {
    return { kind: "invalid", activityId };
  }
  if (typeof data !== "object" || data === null || Array.isArray(data)) {
    return { kind: "invalid", activityId };
  }
  const record = data as Record<string, unknown>;
  const type = record.type;
  if (typeof type !== "string" || !(type in registry)) {
    return { kind: "invalid", activityId };
  }
  const entry = registry[type as LearningType];
  // Validate now so the stream never hands a broken payload to a component.
  if (entry.parse(record, activityId) === null) {
    return { kind: "invalid", activityId };
  }
  return { kind: "component", type: type as LearningType, data: record, activityId };
}

/**
 * Splits accumulated LLM output into prose and learning components.
 *
 * Takes the full text so far rather than a delta, so it is pure and idempotent:
 * calling it on every chunk cannot drift out of sync with the stream the way an
 * incremental state machine can. Text after an unclosed tag is withheld as
 * `pending` — the payload is still arriving and cannot be trusted yet.
 */
export function parseLearningStream(text: string): Segment[] {
  const segments: Segment[] = [];
  const pushText = (t: string) => {
    if (t.trim()) segments.push({ kind: "text", text: t.trim() });
  };

  let rest = text;
  let index = 0;
  for (;;) {
    const openAt = rest.indexOf(OPEN);
    if (openAt === -1) {
      pushText(trimPartialOpenTag(rest));
      return segments;
    }
    pushText(rest.slice(0, openAt));

    const after = rest.slice(openAt + OPEN.length);
    const closeAt = after.indexOf(CLOSE);
    if (closeAt === -1) {
      // Still streaming. Anything after an unclosed tag is part of this payload.
      segments.push({ kind: "pending" });
      return segments;
    }
    // Ordinal, not a content hash: components are only ever appended, so an
    // earlier component keeps its id as more of the stream arrives, which keeps
    // xAPI statements pointing at a stable activity across re-renders.
    segments.push(classify(after.slice(0, closeAt), `streamed-${index}`));
    index++;
    rest = after.slice(closeAt + CLOSE.length);
  }
}

// Self-check: npx tsx components/learning/parse.ts
if (process.argv[1]?.endsWith("parse.ts")) {
  const kinds = (t: string) => parseLearningStream(t).map((s) => s.kind).join(",");
  const quiz = JSON.stringify({
    type: "quiz",
    prompt: "Which is idempotent?",
    options: [
      { id: "A", text: "POST", valid: false, feedback: "no" },
      { id: "B", text: "GET", valid: true, feedback: "yes" },
    ],
  });
  const wrap = (json: string) => `${OPEN}${json}${CLOSE}`;

  console.assert(kinds("just prose") === "text", "plain text");
  console.assert(kinds("") === "", "empty stream yields nothing");
  console.assert(kinds(`Intro ${wrap(quiz)} outro`) === "text,component,text", "text around");
  console.assert(kinds(`${wrap(quiz)}${wrap(quiz)}`) === "component,component", "back to back");

  // Cut-off mid-payload: withheld, never rendered half-parsed.
  console.assert(kinds(`Intro ${OPEN}{"type":"qu`) === "text,pending", "unclosed tag pends");
  console.assert(kinds(`Intro ${OPEN}`) === "text,pending", "bare open tag pends");

  // A partially-arrived open tag must not leak to the reader as prose.
  console.assert(kinds("Intro <LEARNING_COMP") === "text", "partial tag is not prose");
  console.assert(
    parseLearningStream("Intro <LEARNING_COMP")[0]?.kind === "text" &&
      (parseLearningStream("Intro <LEARNING_COMP")[0] as { text: string }).text === "Intro",
    "partial tag trimmed from text"
  );

  // Malformed payloads degrade to `invalid`, never throw.
  console.assert(kinds(wrap("{not json")) === "invalid", "corrupt json");
  console.assert(kinds(wrap("[1,2]")) === "invalid", "array payload");
  console.assert(kinds(wrap('{"type":"unknown"}')) === "invalid", "unknown type");
  console.assert(kinds(wrap('{"type":"quiz"}')) === "invalid", "quiz missing fields");
  console.assert(
    kinds(wrap('{"type":"quiz","prompt":"p","options":[{"id":"A","text":"a","valid":false}]}')) ===
      "invalid",
    "quiz with no correct answer"
  );
  console.assert(
    kinds(wrap('{"type":"flashcard","front":"f","back":""}')) === "invalid",
    "flashcard with empty back"
  );
  console.assert(
    kinds(wrap('{"type":"flashcard","front":"f","back":"b"}')) === "component",
    "valid flashcard"
  );
  console.assert(kinds(wrap("```json\n" + quiz + "\n```")) === "component", "code fences stripped");

  // The property that matters most: every prefix of a real stream is safe.
  const full = `Lead in.\n\n${wrap(quiz)}\n\nMiddle.\n\n${wrap(
    JSON.stringify({ type: "flashcard", front: "f", back: "b" })
  )}\n\nTail.`;
  for (let i = 0; i <= full.length; i++) {
    const segs = parseLearningStream(full.slice(0, i));
    console.assert(!segs.some((s) => s.kind === "invalid"), `prefix ${i} produced invalid`);
    const text = segs
      .filter((s): s is { kind: "text"; text: string } => s.kind === "text")
      .map((s) => s.text)
      .join(" ");
    console.assert(!text.includes("<LEARNING"), `prefix ${i} leaked a tag into prose`);
    console.assert(!text.includes('"type"'), `prefix ${i} leaked payload json into prose`);
  }
  console.assert(parseLearningStream(full).filter((s) => s.kind === "component").length === 2, "final");

  // Every registry demo must survive its own validator. This is what keeps the
  // documented schemas in PROMPT.md honest: the demos are the worked examples,
  // so a validator tightened without updating them fails here.
  for (const [type, e] of Object.entries(registry)) {
    const payload = JSON.stringify({ type, ...e.demo });
    console.assert(kinds(wrap(payload)) === "component", `registry demo "${type}" fails its parser`);
  }

  console.log("parse self-check passed");
}
```

### components/learning/registry.tsx

```tsx
import type { ComponentType, ReactNode } from "react";
import { FlashcardBlock } from "./FlashcardBlock";
import { MasteryMeter } from "./MasteryMeter";
import { QuizBlock } from "./QuizBlock";
import { SequenceBuilder } from "./SequenceBuilder";
import type { XApiStatement } from "./xapi";

type Track = (statement: XApiStatement) => void;

/** Props every learning component accepts. */
export interface LearningComponentProps {
  activityId: string;
  onTrackTelemetry?: Track;
}

interface EntryInput<P extends LearningComponentProps> {
  /** Showcase heading. */
  title: string;
  /** One or two sentences for the showcase. */
  description: string;
  Component: ComponentType<P>;
  /** Example payload. Doubles as the showcase demo and a parser fixture. */
  demo: P;
  /**
   * Validates one streamed `<LEARNING_COMPONENT>` payload into props, or null
   * if it does not conform. This is a trust boundary: the input is model
   * output, so every field is checked rather than assumed.
   *
   * `activityId` is supplied by the parser because the LLM schema has no id
   * field, but xAPI statements need a stable activity to point at.
   */
  parse: (data: Record<string, unknown>, activityId: string) => P | null;
}

const isNonEmptyString = (v: unknown): v is string => typeof v === "string" && v.trim() !== "";

/**
 * Binds a component to its demo payload while the prop type is still concrete.
 * Iterating the registry widens entries to a union, at which point TypeScript
 * can no longer tell that a given demo belongs to a given component — so the
 * pairing is resolved into `render` here instead of being cast at the call site.
 */
const entry = <P extends LearningComponentProps>(e: EntryInput<P>) => ({
  title: e.title,
  description: e.description,
  Component: e.Component,
  demo: e.demo,
  parse: e.parse,
  render: (onTrackTelemetry?: Track): ReactNode => (
    <e.Component {...e.demo} onTrackTelemetry={onTrackTelemetry} />
  ),
  /**
   * Validates and renders one streamed payload, or returns null if it does not
   * conform. Combined into one step for the same union-widening reason as
   * `render`: only here is P concrete enough to pass parsed props to Component.
   */
  parseAndRender: (
    data: Record<string, unknown>,
    activityId: string,
    onTrackTelemetry?: Track
  ): ReactNode | null => {
    const props = e.parse(data, activityId);
    return props ? <e.Component {...props} onTrackTelemetry={onTrackTelemetry} /> : null;
  },
});

/**
 * Single source of truth for the library. Adding a component means adding one
 * entry here: the showcase page and the `<LEARNING_COMPONENT>` stream parser
 * both read from this map rather than keeping their own lists.
 *
 * Keys are the `type` field of the JSON an LLM emits.
 */
export const registry = {
  quiz: entry({
    title: "Quiz",
    description:
      "An inline concept check with immediate feedback. Emits an xAPI “answered” statement on submit — open the console to see it.",
    Component: QuizBlock,
    parse: (data, activityId) => {
      if (!isNonEmptyString(data.prompt) || !Array.isArray(data.options)) return null;
      // A quiz with no options, or with exactly one, is not answerable.
      if (data.options.length < 2) return null;
      const options = data.options.map((o: unknown) => {
        const opt = o as Record<string, unknown>;
        if (!isNonEmptyString(opt?.id) || !isNonEmptyString(opt?.text)) return null;
        return {
          id: opt.id,
          text: opt.text,
          valid: opt.valid === true,
          feedback: typeof opt.feedback === "string" ? opt.feedback : "",
        };
      });
      if (options.some((o) => o === null)) return null;
      const valid = options as NonNullable<(typeof options)[number]>[];
      // Without a correct answer the feedback and the xAPI `success` flag are
      // both meaningless, so treat it as malformed rather than render it.
      if (!valid.some((o) => o.valid)) return null;
      return { activityId, prompt: data.prompt, options: valid };
    },
    demo: {
      activityId: "http-idempotency-check",
      prompt: "Which HTTP method should be safely designed as idempotent?",
      options: [
        {
          id: "A",
          text: "POST",
          valid: false,
          feedback: "POST creates new resources and is typically non-idempotent.",
        },
        {
          id: "B",
          text: "GET",
          valid: true,
          feedback: "Correct! Multiple GET calls return the same data without altering state.",
        },
      ],
    },
  }),
  flashcard: entry({
    title: "Flashcard",
    description:
      "A term on the front, the explanation on the back. Emits an xAPI “experienced” statement the first time it is revealed.",
    Component: FlashcardBlock,
    parse: (data, activityId) =>
      isNonEmptyString(data.front) && isNonEmptyString(data.back)
        ? { activityId, front: data.front, back: data.back }
        : null,
    demo: {
      activityId: "idempotency-definition",
      front: "What does it mean for an HTTP method to be idempotent?",
      back: "Making the same request many times has the same effect as making it once.",
    },
  }),
  sequence: entry({
    title: "Sequence builder",
    description:
      "Steps arrive shuffled and the learner orders them. Reordering is keyboard-driven, and submitting emits an xAPI “answered” statement carrying the submitted order.",
    Component: SequenceBuilder,
    parse: (data, activityId) => {
      if (!isNonEmptyString(data.prompt) || !Array.isArray(data.steps)) return null;
      // Two steps is a coin flip, not an ordering task — and the anti-identity
      // rotation in the component would make the answer the reverse every time.
      if (data.steps.length < 3) return null;
      const steps = data.steps.map((s: unknown) => {
        const step = s as Record<string, unknown>;
        if (!isNonEmptyString(step?.id) || !isNonEmptyString(step?.text)) return null;
        return { id: step.id, text: step.text };
      });
      if (steps.some((s) => s === null)) return null;
      const valid = steps as NonNullable<(typeof steps)[number]>[];
      // Duplicate ids would make the submitted order ambiguous in the xAPI
      // response and break React's keys.
      if (new Set(valid.map((s) => s.id)).size !== valid.length) return null;
      return { activityId, prompt: data.prompt, steps: valid };
    },
    demo: {
      activityId: "http-request-lifecycle",
      prompt: "Order the steps of an HTTP request.",
      steps: [
        { id: "dns", text: "Resolve the hostname via DNS" },
        { id: "tcp", text: "Open a TCP connection" },
        { id: "tls", text: "Negotiate TLS" },
        { id: "send", text: "Send the request" },
        { id: "recv", text: "Receive the response" },
      ],
    },
  }),
  mastery: entry({
    title: "Mastery meter",
    description:
      "The tutor's read on where the learner stands across a topic, plus a self-rating that emits an xAPI “rated” statement — the signal for what to teach next.",
    Component: MasteryMeter,
    parse: (data, activityId) => {
      if (!isNonEmptyString(data.title) || !Array.isArray(data.skills)) return null;
      if (data.skills.length === 0) return null;
      const skills = data.skills.map((s: unknown) => {
        const skill = s as Record<string, unknown>;
        if (!isNonEmptyString(skill?.id) || !isNonEmptyString(skill?.label)) return null;
        // Out-of-range levels would overflow the bar and print figures like
        // "340%". Reject rather than clamp: a model that far off the schema is
        // probably wrong about the content too.
        const level = skill.level;
        if (typeof level !== "number" || !Number.isFinite(level) || level < 0 || level > 1) {
          return null;
        }
        return { id: skill.id, label: skill.label, level };
      });
      if (skills.some((s) => s === null)) return null;
      const valid = skills as NonNullable<(typeof skills)[number]>[];
      if (new Set(valid.map((s) => s.id)).size !== valid.length) return null;
      return { activityId, title: data.title, skills: valid };
    },
    demo: {
      activityId: "rest-fundamentals",
      title: "REST fundamentals",
      skills: [
        { id: "methods", label: "HTTP methods", level: 0.8 },
        { id: "idempotency", label: "Idempotency", level: 0.6 },
        { id: "status", label: "Status codes", level: 0.4 },
        { id: "caching", label: "Caching headers", level: 0.2 },
      ],
    },
  }),
};

export type LearningType = keyof typeof registry;
```

### components/learning/LearningStream.tsx

```tsx
"use client";
import { ComponentBoundary } from "./ComponentBoundary";
import { parseLearningStream } from "./parse";
import { registry } from "./registry";
import type { XApiStatement } from "./xapi";

const Unavailable = () => (
  <p className="text-muted-foreground border-muted-foreground/30 rounded-lg border border-dashed p-3 text-xs">
    An activity could not be displayed.
  </p>
);

export interface LearningStreamProps {
  /** Everything the model has emitted so far, not just the latest chunk. */
  text: string;
  onTrackTelemetry?: (statement: XApiStatement) => void;
}

/**
 * Renders a model's output, hydrating `<LEARNING_COMPONENT>` payloads into live
 * components as they arrive. Components render inline in the host layout — no
 * iframe, no post-processing pass.
 */
export function LearningStream({ text, onTrackTelemetry }: LearningStreamProps) {
  const segments = parseLearningStream(text);

  return (
    <div className="w-full space-y-4">
      {segments.map((segment, i) => {
        switch (segment.kind) {
          case "text":
            return (
              <p key={`text-${i}`} className="text-sm leading-relaxed">
                {segment.text}
              </p>
            );

          case "component":
            return (
              // Keyed by activity id, not array index: the id is stable as more
              // of the stream arrives, so a learner's in-progress answer is not
              // reset by later chunks remounting the component.
              <div key={segment.activityId} className="flex justify-center py-1">
                <ComponentBoundary fallback={<Unavailable />}>
                  {registry[segment.type].parseAndRender(
                    segment.data,
                    segment.activityId,
                    onTrackTelemetry
                  )}
                </ComponentBoundary>
              </div>
            );

          case "invalid":
            return <Unavailable key={segment.activityId} />;

          case "pending":
            return (
              <div
                key="pending"
                aria-hidden
                className="bg-card mx-auto w-full max-w-md animate-pulse rounded-xl border p-4 shadow-sm"
              >
                <div className="bg-muted mb-3 h-3 w-24 rounded" />
                <div className="bg-muted mb-2 h-3 w-full rounded" />
                <div className="bg-muted h-8 w-full rounded-lg" />
              </div>
            );
        }
      })}
    </div>
  );
}
```

## Protocol

# LLM protocol

Paste the block below into your backend's system prompt (OpenAI, Anthropic, or an
LMS-specific MCP server). It is what makes a model emit payloads this library can hydrate.

The schemas here are enforced by the validators in `components/learning/registry.tsx`. Those
validators are the source of truth; the self-check in `components/learning/parse.ts` asserts
that every worked example below still passes them, so this file cannot silently drift.

## What the parser tolerates

Models do not follow instructions perfectly, so the parser is deliberately forgiving of the
failures that actually happen in production:

| Model behaviour | What the parser does |
|---|---|
| Payload still streaming | Renders a placeholder; never shows half-parsed JSON |
| Stream cut off mid-tag | Same — the partial tag is withheld from the prose |
| Wraps the JSON in ```json fences | Strips the fences and parses anyway |
| Emits malformed JSON | Renders "An activity could not be displayed"; the surrounding lesson still renders |
| Emits an unknown `type` | Same as malformed |
| Emits a quiz with no correct option | Rejected — `success` in the xAPI statement would be meaningless |

What it will not do is render a component from a payload that failed validation.

## The system prompt block

```text
You are an expert AI tutor. While teaching the user, you must periodically test their
understanding using custom interactive elements.

When you want to issue an interactive checkpoint, stop writing standard text and output
exactly one JSON object wrapped inside structural <LEARNING_COMPONENT> tags.

CRITICAL RULES:
1. Do not include markdown code block syntax (like ```json) inside the tags.
2. The payload must strictly validate against the JSON schemas provided below.
3. Keep explanation strings concise, objective, and supportive.
4. Continue the lesson in prose after the closing tag.

[SCHEMA: QUIZ]
{
  "type": "quiz",
  "prompt": "The conceptual question being asked.",
  "options": [
    { "id": "A", "text": "Option text", "valid": true,  "feedback": "Why this is right." },
    { "id": "B", "text": "Option text", "valid": false, "feedback": "Correction or hint." }
  ]
}
Requires at least two options, and at least one with "valid": true.

[SCHEMA: FLASHCARD]
{
  "type": "flashcard",
  "front": "Term, question, or snippet to memorize.",
  "back": "The answer, explanation, or core concept definition."
}
Both fields are required and must be non-empty.

[SCHEMA: SEQUENCE]
{
  "type": "sequence",
  "prompt": "What the learner is ordering.",
  "steps": [
    { "id": "dns",  "text": "Resolve the hostname via DNS" },
    { "id": "tcp",  "text": "Open a TCP connection" },
    { "id": "send", "text": "Send the request" }
  ]
}
List the steps in the CORRECT order — the component shuffles them for display.
Requires at least three steps with unique ids.

[SCHEMA: MASTERY]
{
  "type": "mastery",
  "title": "The topic being assessed.",
  "skills": [
    { "id": "methods",     "label": "HTTP methods", "level": 0.8 },
    { "id": "idempotency", "label": "Idempotency",  "level": 0.6 }
  ]
}
"level" is your assessment of the learner from 0 to 1, based on the conversation
so far. Ids must be unique. Emit this at the end of a topic, not mid-explanation.

[EXAMPLE IN-LINE OUTPUT]
That wraps up how REST endpoints work. Let's see if you can spot the difference here:

<LEARNING_COMPONENT>
{
  "type": "quiz",
  "prompt": "Which HTTP method should be safely designed as idempotent?",
  "options": [
    { "id": "A", "text": "POST", "valid": false, "feedback": "POST creates new resources and is typically non-idempotent." },
    { "id": "B", "text": "GET", "valid": true, "feedback": "Correct! Multiple GET calls return the same data without altering state." }
  ]
}
</LEARNING_COMPONENT>

What thoughts do you have on how this maps to database actions?
```

## Wiring it up

```tsx
import { LearningStream } from "@/components/learning/LearningStream";

// `text` is everything the model has emitted so far, not just the latest chunk.
<LearningStream text={text} onTrackTelemetry={(s) => sendToLRS(s)} />;
```

`LearningStream` is pure with respect to `text`: re-parsing the full buffer on every chunk is
what keeps it from drifting out of sync with the stream. Components are keyed by a stable
activity id, so a learner's in-progress answer survives later chunks arriving.

## Telemetry

Every interaction emits an xAPI statement to `onTrackTelemetry`, ready to forward to a
Learning Record Store. There is no network call built in — the host app decides where it goes.

```json
{
  "verb": { "id": "http://adlnet.gov/expapi/verbs/answered", "display": { "en-US": "answered" } },
  "object": {
    "id": "http://beadkit.dev/activities/streamed-0",
    "definition": { "name": { "en-US": "Which HTTP method should be safely designed as idempotent?" } }
  },
  "result": { "response": "B", "success": true, "completion": true, "duration": "PT14S" }
}
```

A flashcard emits `experienced` with no `response` or `success`: those fields are omitted
rather than sent as null, because an LRS reads a present-but-null `success` as a scored
attempt. Flipping a card back and forth emits one statement, not one per flip.

The `actor` field is intentionally absent. Identity belongs to the host app, which should
merge it in before forwarding to its LRS.