Direction: every widget kind expressible in A2UI — the registry defines an a2learn catalog

[adamstankiewicz]

The direction

All widget kinds should be authored against A2UI/AG-UI rather than living only in the bespoke MCP Apps shell. Stated as a decision about what the product is: the registry's wire form becomes an A2UI catalog, and the React components become a renderer of that catalog — one implementation among possible many — instead of being the format themselves.

What this cannot mean (honesty constraints)

• It cannot mean flattening rich mechanics into the basic catalog. Drag-sort rendered as checkboxes measures something different from drag-sort; a degraded projection must stay labeled as one (the current mapper's stated-fidelity-limits pattern), and assesses must track the mechanics actually rendered, never the kind's name.
• It cannot mean the model authoring component trees freeform. Invariant 1 gets stronger here: surfaces are pure data, model output still fills Zod specs, and the mapping spec→surface stays human-written code.

The shape: invert the relationship

A2UI's extension mechanism is the custom catalog. The a2learn catalog is the registry, projected:

• each widget kind = one catalog component; its props schema generated from the kind's existing Zod spec (zod → JSON schema is mechanical), so the catalog cannot drift from the registry;
• surfaces referencing the a2learn catalog are full-fidelity; the same spec also projects to the basic catalog where honest, as the universal degraded path (two-tier delivery, both truthfully labeled);
• evidence returns via A2UI actions (the existing completedAction pattern: no verdict without real checking, gated on assesses) and crosses AG-UI transports as the namespaced a2learn.* custom events /api/pathway/agui already established.

Staged path

1. Widen basic-catalog coverage where honest — selected-response/short-answer shapes via the catalog's input components (CheckBox, TextField); use the A2UI data model for local state (fixes the flashcard flip degradation). Fixture pair per kind, per the conformance gate.
2. Registry-owned mapping — the optional a2ui field on the registry entry (already anticipated in src/lib/a2learn/a2ui.ts's header, tied to the registry-owned-semantics refactor), so adding a kind stays one file.
3. The a2learn catalog — versioned, served, schema-vendored like the upstream ones; conformance validates both directions (our surfaces against A2UI envelope schemas, catalog component instances against the generated props schemas), with negative controls.
4. The React registry becomes a catalog renderer — the MCP Apps shell re-based as a renderer of a2learn-catalog surfaces rather than a parallel bespoke path.

Relations

• Un-drafts docs: the a2learn format draft #74 when reached: an a2learn manifest + catalog actually used by the OSS is exactly the phase-2 condition recorded there.
• Builds on Migrate /api/mcp to the SDK's webStandardStreamableHttp; unify the three server transports #92's single server definition and feeds Full teacher journey over MCP: assign_pathway + get_pathway_results (+ teacherNote on build_pathway) #94's evidence journey.
• Depends on the registry-owned-semantics refactor; each phase is its own PR chain with its own gates.

Filed as the direction record per the governance rule that contract changes start as issues; phase 1 is actionable as soon as the current stack (#93) clears.

🤖 Generated with Claude Code

[adamstankiewicz]

Design addition: an interaction-primitives tier (from building the demo renderer)

Building the two-tier demo forced the basic-catalog renderer to grow compositional heuristics: a Card whose sole child is a two-tab Tabs renders as a flip card; a horizontal List followed by an action Button renders as a deck whose final Next becomes the action. They work, but each heuristic is an admission that the basic catalog lacks a word — the behavior lives in the renderer's guess instead of the surface's contract. And step-reveal exposed the ceiling: its defining behavior (gated, one-at-a-time disclosure) has no basic-catalog encoding at all — the best honest projection is a freely-paging deck.

So the a2learn catalog should have three granularities, not one:

1. Basic projection (exists): universal, honestly degraded.
2. a2learn interaction primitives (new): a small set of behavioral components — implementable by any host in an afternoon, faithful to the pedagogy:
   • a2learn:Stepper — steps: [{title, child}], disclosure: "gated" | "free", revealed: "accumulate" | "replace", completeAction fired when the last step is advanced past. Captures step-reveal/narrated-card behavior exactly.
   • a2learn:FlipDeck — cards: [{front, back}], paged, per-card flip, completeAction. Makes today's two renderer heuristics a contract.
3. a2learn whole-widget components (the current draft): exact parity, registry as reference renderer — for hosts that adopt fully.

The middle tier is the adoption wedge: a host implementing half a dozen primitives renders most kinds behavior-faithfully without implementing every widget, and the primitives' contracts (gating, completion actions) plug straight into the #99 event vocabulary. The renderer heuristics stay only as fallbacks for pure-basic surfaces.

🤖 Generated with Claude Code

[adamstankiewicz]

Correction to the primitives tier: generic and parameterized, not per-kind

Adam's steer, which supersedes the Stepper/FlipDeck sketch above: kind-shaped primitives just recreate the whole-widget problem at smaller grain. The primitives tier should be a small set of generic behavior words with policies as data, so new activity shapes compose at generation time — by a mapper today, by a planner model tomorrow — with no new component code per shape.

Prototyped on feat/a2ui-agui-conformance (src/lib/a2learn/primitives.ts, live on /demo/a2ui as a third column):

• a2learn:Sequence — ordered children + traversal policy { order: linear|free, disclosure: gated|all, revealed: accumulate|replace } + completeAction fired past the end.
• a2learn:Reveal — one thing with N titled faces, tap to turn.

Proof by composition: step-reveal IS Sequence(linear, gated, accumulate); a flashcard deck IS Sequence(free, all, replace) of Reveal(front, back). A hypothetical kind needing any other policy mix is pure data. The draft catalog is declared basic ∪ primitives, so composition content reuses every basic-catalog word.

Invariant-1 note: what a model would generate is a schema-validatable composition tree; primitive implementations stay human-written renderer code. Assessment semantics stay out of this tier until #99's vocabulary lands — a Choice/Input primitive with verdict semantics must gate on assesses by contract, not by convention.

🤖 Generated with Claude Code

[adamstankiewicz]

Research: the pedagogical primitive vocabulary (QTI / H5P / Perseus / learning sciences)

Survey of existing K-12 interaction vocabularies, synthesized through the atomic-design lens. Full trail at the bottom; the design-relevant core:

The proliferation lesson. QTI 3.0 defines ~20 interaction types (choice, order, match, gap-match, hotspot, text-entry, numeric, drawing, media…) — but they collapse into one parameterized primitive: Response with a type enum and cardinality (single|multiple|ordered). H5P ships 60+ content types, but most are compositions (Interactive Video = Content + embedded Checks; Question Set = Sequence of Responses; Branching Scenario = Sequence with branching policy). Perseus tells the same story (radio/numeric/expression = Response types; grapher/manipulatives = an ungraded Interaction). The vocabulary below covers ~90-100% of each source's surface via parameters, not per-kind entries.

The vocabulary (~10 words), layered:

Atoms — content, never interactive, composable inside molecules:

• Callout — intent as data (shipped in draft; DITA's note taxonomy is the precedent for the intent enum)
• Term — vocabulary anchor: label, definition, reveal mode
• Example — a concrete/worked case, with optional fadeSteps (worked-example fading, Ge et al. 2012)

Molecules — behavior, policy-parameterized:

• Sequence — shipped: order/disclosure/revealed policy; grows branching (verdict-conditional next) to cover H5P Branching Scenario and adaptive flow
• Reveal — shipped: N faces; grows trigger policy (click|prerequisite) to cover hint escalation
• Check — formative pulse: prompt + responseType + feedbackMode; verdict informs, never records
• Response — summative assessed input: the QTI-collapsing primitive (type enum: choice|text|numeric|expression|match|order|hotspot|drawing; scoring declared upfront)
• Interaction — exploratory tool (grapher, manipulative, sandbox): learner agency, real-time feedback, no verdict by design
• Elaboration — self-explanation / elaborative-interrogation prompt ("why?" as an interaction, not just a callout) — the highest-leverage pattern per the learning-science evidence (Chi & Wylie's ICAP; Dunlosky et al. 2013)
• Content — media atom-carrier (video/audio/image with transcript/fallback)

Verdict hygiene (the invariant-3 / #99 junction): only Response carries a summative verdict, Check a formative one that must never reach a transcript, Elaboration optionally rubric-scored — everything else is contractually verdict-free. The schema should force the declaration (assessmentType: summative|formative) rather than trusting convention; scoring logic is pre-authored, never model-generated at render time.

ICAP as the quality lens (Chi & Wylie 2014): the framework ranks Interactive > Constructive > Active > Passive engagement — useful as planner guidance metadata on primitives (Elaboration/Interaction rank above bare Content), not as schema.

Confirmed: no educational component catalogs exist yet in the A2UI ecosystem — the custom-catalog mechanism is explicitly designed for this and nobody has claimed the space.

Sources: QTI 3.0 · H5P content types · Perseus · ICAP (Chi & Wylie 2014) · Dunlosky et al. strategies · DITA note types · Ge et al. 2012 scaffolding · A2UI

🤖 Generated with Claude Code