MDMA

Markdown Document with Mounted Applications

Interactive documents from Markdown. Built for next gen-apps

🌐 Website   ·   🚀 Live Demo   ·   📖 Docs   ·   💬 Discord   ·   🤗 Model

Why MDMA?

AI conversations today are plain text — the user reads a response and manually acts on it. MDMA changes that. When an LLM knows the MDMA spec, it can respond with interactive components (forms, tables, approval gates) instead of just text. The conversation becomes actionable: the user fills out a form, approves a step, or reviews structured data — all inline, with a predictable schema that your app already knows how to render and process.

No custom UI per use case. No parsing free-form text. The AI generates structured, validated components and your frontend renders them instantly.

What is MDMA?

MDMA extends Markdown with interactive components defined in fenced mdma code blocks. A regular Markdown file becomes an interactive application:

# Patient Intake

```mdma
type: form
id: intake-form
fields:
  - name: patient-name
    type: text
    label: "Full Name"
    required: true
    sensitive: true
  - name: email
    type: email
    label: "Email"
    required: true
    sensitive: true
  - name: reason
    type: textarea
    label: "Reason for Visit"
    required: true
onSubmit: submit-intake
```

```mdma
type: button
id: submit-btn
text: "Submit Intake Form"
variant: primary
onAction: submit
```

Speed comparison

Same scenario, two models. GPT-5.5 and our own hosted MDMA-IL model.

Our model is available on Hugging Face: MobileReality/mdma-gemma4-26b-dsl-unsloth-v1

GPT-5.5	Our own hosted model

MDMA_AUTHOR prompt matrix

Each cell shows the pass rate of the model-specialized MDMA_AUTHOR prompt variant on the listed eval suite.

✅ 100% on the suite.

🟡 Scoring between 80–99% on the suite.

🔴 Scoring below 80% on the suite.

Variant	one-shot	one-shot with custom prompt	conversation	specific flow of conversation
OpenAI
gpt-5.6-sol	✅	✅	✅	✅
gpt-5.6-terra	✅	✅	✅	✅
gpt-5.6-luna	✅	✅	✅	✅
gpt-5.5	✅	✅	✅	✅
gpt-5.4	✅	✅ †	✅ †	✅ †
gpt-5.4-mini	✅	✅	✅ *	✅ *
gpt-5.4-nano	✅	✅	✅ *	✅ *
gpt-5.2	✅	✅	✅	✅
gpt-5.1	✅	✅	✅	✅
gpt-5 [i]	✅	✅	✅	✅
gpt-5-mini [i]	✅	✅	✅ *	✅ *
gpt-5-nano [i]	✅	✅	🟡 *	🟡 *
gpt-4.1	✅	✅	✅	✅
gpt-4.1-mini	✅	✅	✅ *	✅ *
gpt-4.1-nano	✅	✅	✅ *	🟡 *
Anthropic
claude-opus-4.8	✅	✅	✅	✅
claude-opus-4.7	✅	✅	✅	✅
claude-opus-4.6	✅	✅	✅	✅
claude-sonnet-4.6	✅	✅	✅	✅
claude-haiku-4.5	✅	✅	✅ *	✅ *
claude-fable-5	✅	✅	✅	✅
Google
gemini-3.5-flash	✅	✅	✅	✅
gemini-3.1-pro-preview	✅	✅	✅	🟡 ‡
gemini-3.1-pro-preview-customtools	✅	✅	✅	✅
gemini-3.1-flash-lite-preview	✅	✅	✅ *	✅ *
gemini-3-flash-preview	✅	✅	✅ *	✅ *
gemini-2.5-pro	✅	✅	✅	✅
gemini-2.5-flash	✅	✅	✅ *	✅ *
gemini-2.5-flash-lite	✅	✅	✅ *	✅ *
xAI
grok-4.3 [i]	🟡	🔴	🔴	🔴
grok-4.20	✅	✅	✅	✅
grok-4.5	✅	✅	✅	✅
Zhipu (z.ai)
glm-4-plus	TBD	TBD	TBD	TBD
Moonshot
kimi-k2	TBD	TBD	TBD	TBD
Alibaba
qwen3-max	TBD	TBD	TBD	TBD
MiniMax
minimax-m1	TBD	TBD	TBD	TBD
Other
model	—	—	—	—

Don't see your model? Add a prompt variant under packages/prompt-pack/src/prompts/mdma-author/<vendor>/ and open a PR — we'll run the eval suite and add it to this table.

† gpt-5.4 intermittent duplication bug — gpt-5.4 passes one-shot evals reliably but shows a non-deterministic output duplication in multi-turn, custom-prompt, and flow evals (~7–15% of runs). The model generates a complete, correct response and then immediately re-emits the entire output verbatim, causing [duplicate-ids] validation errors. This is a known model-level issue unrelated to the prompt variant. See the OpenAI community thread for details. If this affects your use case, prefer gpt-5.5 or gpt-5.2.

‡ gemini-3.1-pro-preview stochastic preamble loop — on ~7–15% of flow-eval runs, the model emits a chain-of-thought as visible Markdown prose (e.g. **Investigating Production Errors** repeated 3–5 times) instead of opening a ```mdma block, producing either [yaml-correctness: outside fenced block] or [duplicate-ids] errors. Per Google's official Gemini 3 prompting guide, this is a model-level behavior driven by temperature/sampling — prompt-level fixes shift which test loops rather than eliminating the loops. If deterministic flow output matters, prefer gemini-2.5-pro for production multi-step flows.

* Smaller / lower-tier models from any lab (OpenAI mini · nano, Anthropic Haiku, Google Gemini Flash, etc.) pass our eval suites, which exercise short, structured test cases. In longer real-world conversations they tend to hallucinate, forget earlier turns, or drift from the spec. For production use that involves multi-turn dialogue or stateful flows, prefer the flagship-tier model from the same family.

[i] Noticeably slow response times — single-turn responses commonly take tens of seconds and full eval runs measure in minutes.

MDMA_FIXER prompt matrix

Each cell shows the pass rate of the model-specialized MDMA_FIXER prompt variant on the single-block fixer eval (16 tests covering structural fixes, bindings, PII, forms, tables/charts, approvals, and custom-component extraction). The fixer is what powers automatic repair of LLM output that fails validate() — every supported model lands at ✅ via model-tailored inline guards (no-leading-separator, preserve-input-structure, table-key-direction, replace-all-placeholders, fix-all-listed-errors, etc.).

✅ 100% on the single-block fixer eval (16/16).

Variant	single-block fixer	notes for testing
OpenAI
gpt-5.6-sol	✅
gpt-5.6-terra	✅
gpt-5.6-luna	✅
gpt-5.5	✅
gpt-5.4	✅
gpt-5.4-mini	✅
gpt-5.4-nano	✅
gpt-5.2	✅
gpt-5.1	✅
gpt-5	✅
gpt-5-mini	✅
gpt-5-nano	✅
gpt-4.1	✅
gpt-4.1-mini	✅
gpt-4.1-nano	✅
Anthropic
claude-opus-4.8	✅
claude-opus-4.7	✅
claude-opus-4.6	✅
claude-sonnet	✅	catch-all variant — matches claude-sonnet-4-5, claude-sonnet-4-6, etc.
claude-haiku	✅
claude-fable-5	✅ ‡	requires reasoning.exclude: true (wired in evals/promptfooconfig.fixer.js)
Google
gemini-3.5-flash	✅ ‡	requires reasoning.exclude: true; adds an inline no-leading-separator guard
gemini-3.1-pro-preview	✅ ‡	requires OpenRouter reasoning.exclude: true (already wired in evals/promptfooconfig.fixer.js)
gemini-3.1-pro-preview-customtools	✅ ‡	same reasoning.exclude requirement
gemini-3.1-flash-lite-preview	✅
gemini-3-flash-preview	✅
gemini-2.5-pro	✅ ‡	same reasoning.exclude requirement
gemini-2.5-flash	✅
gemini-2.5-flash-lite	✅
xAI
grok-4.3	✅ ‡	minimal prompt + reasoning.exclude: true — extra framing regresses Grok 4.3
grok-4.20	✅
grok-4.5	✅ ‡	requires reasoning.exclude: true (hidden-reasoning model)

‡ Reasoning-token leak suppression — for reasoning-flavoured Gemini Pro variants and Grok 4.3, the fixer would otherwise see visible "Thinking: Topic" prose prepended to every response. The eval config sets passthrough.reasoning.exclude: true (and the demo's usePreviewValidation does the same per-provider) to strip reasoning tokens from the response body at the API layer rather than at the prompt layer.

Components

10 built-in component types, all rendered out of the box by @mobile-reality/mdma-renderer-react:

Component	Type key	Description
Form	form	Multi-field forms with text, number, email, date, select, checkbox, textarea, and file fields. Supports validation, required fields, default values, and sensitive (PII) flags.
Button	button	Action buttons with primary, secondary, and danger variants.
Tasklist	tasklist	Interactive checkbox task items with labels.
Table	table	Data tables with typed columns and row data.
Chart	chart	Table fallback by default — renders chart data as a simple HTML table to avoid forcing a charting dependency (~400KB). Override with your own renderer (e.g. recharts) via customizations.components.chart (see Custom Chart Renderer below).
Callout	callout	Alert banners with info, warning, error, and success variants. Supports optional title and dismiss button.
Approval Gate	approval-gate	Approve/deny workflow gates with pending, approved, and denied states.
Webhook	webhook	Webhook triggers with idle, executing, success, and error status indicators.
Thinking	thinking	Collapsible thinking/reasoning blocks that show the AI's chain of thought.
Custom	custom	Host-extensible escape hatch — a stable envelope (name + open props + actions) that dispatches to a host-registered variant renderer. Register a variant's schema/behavior with registerCustomComponent and its renderer via customizations.customVariants. Use only when no built-in type fits.

Additionally, standard Markdown content (headings, paragraphs, lists, code blocks, images, links, tables, etc.) is rendered inline between components.

Custom Chart Renderer

The built-in chart renderer intentionally renders data as a plain table so the library stays lightweight. To get actual charts, register a custom renderer:

import { MdmaDocument } from '@mobile-reality/mdma-renderer-react';
import { MyRechartsRenderer } from './MyRechartsRenderer';

function App({ ast, store }) {
  return (
    <MdmaDocument
      ast={ast}
      store={store}
      customizations={{
        components: {
          chart: MyRechartsRenderer,
        },
      }}
    />
  );
}

This pattern works for overriding any built-in component — pass a custom React component under customizations.components.<type>.

Installation

# Core — parse and run MDMA documents
npm install @mobile-reality/mdma-parser @mobile-reality/mdma-runtime

# React rendering
npm install @mobile-reality/mdma-renderer-react

# AI authoring — system prompts for LLM-based generation
npm install @mobile-reality/mdma-prompt-pack

# Validation — static analysis for MDMA documents
npm install @mobile-reality/mdma-validator

# CLI — interactive prompt builder + document validation
npx @mobile-reality/mdma-cli

All packages are published under the @mobile-reality npm org.

Usage

import { unified } from 'unified';
import remarkParse from 'remark-parse';
import remarkGfm from 'remark-gfm';
import { remarkMdma } from '@mobile-reality/mdma-parser';
import { createDocumentStore } from '@mobile-reality/mdma-runtime';
import type { MdmaRoot } from '@mobile-reality/mdma-spec';

// 1. Parse markdown into AST
const processor = unified().use(remarkParse).use(remarkGfm).use(remarkMdma);
const tree = processor.parse(markdown);
const ast = (await processor.run(tree)) as MdmaRoot;

// 2. Create a reactive document store
const store = createDocumentStore(ast, {
  documentId: 'my-doc',
  sessionId: crypto.randomUUID(),
});

// 3. Subscribe to state changes
store.subscribe((state) => {
  console.log('Bindings:', state.bindings);
});

// 4. Dispatch user actions
store.dispatch({
  type: 'FIELD_CHANGED',
  componentId: 'intake-form',
  field: 'patient-name',
  value: 'Jane Doe',
});

In a Chat

import { buildSystemPrompt, getAuthorPromptVariant } from '@mobile-reality/mdma-prompt-pack';

// Pick the prompt variant tuned for your model (falls back to default if unknown)
const { prompt: authorPrompt } = getAuthorPromptVariant('google/gemini-2.5-pro');

// Optionally layer a custom prompt on top for domain-specific generation
const systemPrompt = buildSystemPrompt({
  authorPrompt,
  customPrompt: `You are a bug tracking assistant. When a user reports a bug,
always generate a single form component matching this exact structure:

\`\`\`mdma
type: form
id: bug-report
fields:
  - name: title
    type: text
    label: "Bug Title"
    required: true
  - name: severity
    type: select
    label: "Severity"
    options:
      - { label: Critical, value: critical }
      - { label: High, value: high }
      - { label: Medium, value: medium }
      - { label: Low, value: low }
  - name: steps
    type: textarea
    label: "Steps to Reproduce"
    required: true
  - name: expected
    type: textarea
    label: "Expected Behavior"
  - name: actual
    type: textarea
    label: "Actual Behavior"
onSubmit: submit-bug-report
\`\`\``,
});

// Send to any OpenAI-compatible API
const response = await fetch('https://api.openai.com/v1/chat/completions', {
  method: 'POST',
  headers: { Authorization: `Bearer ${apiKey}` },
  body: JSON.stringify({
    model: 'gemini-2.5-pro',
    messages: [
      { role: 'system', content: systemPrompt },
      { role: 'user', content: 'The login page crashes after entering my password.' },
    ],
  }),
});

// The LLM responds with regular markdown containing ```mdma blocks
// Parse it into an AST + store as shown above

React

import { MdmaDocument } from '@mobile-reality/mdma-renderer-react';
import '@mobile-reality/mdma-renderer-react/styles.css'; // default styles

function App({ ast, store }) {
  return <MdmaDocument ast={ast} store={store} />;
}

Note: The styles.css import provides default styling for all MDMA components (forms, tables, callouts, animations, etc.). It's optional — you can write your own styles targeting the .mdma-* CSS classes instead.

Theming

Both renderers accept a theme prop on MdmaDocument, so theming is entirely opt-in — omit it and you get the default light look. Pass a built-in palette, follow the OS preference, or hand over a full custom token object:

<MdmaDocument ast={ast} store={store} theme="dark" />   // built-in dark palette
<MdmaDocument ast={ast} store={store} theme="auto" />   // follows OS light/dark
<MdmaDocument ast={ast} store={store} theme={myTheme} /> // custom MdmaTheme tokens

The web renderers (renderer-react, renderer-vue) and the native one (renderer-react-native) share the same MdmaTheme token shape, so a theme object is portable between them. On the web, tokens are applied as --mdma-* CSS variables (still fully overridable in your own CSS); on native, renderers read them via useMdmaTheme(). See the Theming guide for the full token reference.

Packages

Package	Description
@mobile-reality/mdma-spec	The foundation of the MDMA ecosystem — Zod schemas, TypeScript types, and AST definitions for all 10 component types. Every other package depends on spec for validation and type safety.
@mobile-reality/mdma-parser	A remark plugin that transforms standard Markdown into an MDMA-extended AST. Extracts mdma code blocks, validates YAML against component schemas, and builds a binding dependency graph.
@mobile-reality/mdma-runtime	Headless state management engine for MDMA documents — like a mini state specialized for interactive documents. Manages reactive bindings, dispatches actions, enforces environment policies, and writes every event to a tamper-evident audit log with automatic PII redaction.
@mobile-reality/mdma-attachables-core	Handlers for 7 of the 10 component types — the ones that manage state (form, button, tasklist, table, callout, approval-gate, webhook). Chart and thinking are display-only and rendered directly without state handlers.
@mobile-reality/mdma-renderer-react	React rendering layer with components for all 10 MDMA types and hooks for state access. Provides MdmaDocument for full-document rendering and useComponentState/useBinding for fine-grained reactivity.
@mobile-reality/mdma-renderer-vue	Vue 3 rendering layer — the same surface as the React renderer, in Vue idiom: MdmaDocument, MdmaBlock, and composables (useComponentState/useBinding) that return ComputedRefs. Ships the same styles.css, so a theme is portable between the two web renderers.
@mobile-reality/mdma-prompt-pack	System prompts that teach LLMs how to author valid MDMA documents. Ships model-specialised variants for OpenAI, Anthropic, Google, and xAI — select one with getAuthorPromptVariant(modelId). Exports buildSystemPrompt() to combine the variant with optional custom instructions for domain-specific generation.
@mobile-reality/mdma-validator	Static analysis engine with 17 lint rules covering YAML correctness, schema conformance, ID uniqueness, binding syntax, action references, PII sensitivity, expected component verification, and flow ordering. Includes 6 auto-fix strategies and fuzzy type/ID suggestions. Powers programmatic validation in CI pipelines and custom tooling.
@mobile-reality/mdma-cli	Interactive CLI tool for creating custom MDMA prompts. Opens a local web app where you visually select components, configure fields, set domain rules and trigger conditions, then an LLM generates a tailored customPrompt for use with buildSystemPrompt(). Also includes a validate command for static document analysis.
@mobile-reality/mdma-mcp	MCP (Model Context Protocol) server that exposes MDMA spec, prompts, and tooling to AI assistants. Tools: get-spec, get-prompt (with optional variantId for model-optimised prompts), list-prompt-variants, build-system-prompt, validate-prompt, list-packages. Works with Claude Desktop, VS Code, Cursor, and any MCP-compatible client.

Architecture

@mobile-reality/mdma-spec                  Format specification + Zod schemas
  ├── @mobile-reality/mdma-parser          Markdown → MDMA AST (remark plugin)
  ├── @mobile-reality/mdma-prompt-pack     AI authoring prompts
  ├── @mobile-reality/mdma-validator       Document validation
  └── @mobile-reality/mdma-runtime         State / events / policy engine
        └── @mobile-reality/mdma-attachables-core   Component handlers
              ├── @mobile-reality/mdma-renderer-react   React components
              └── @mobile-reality/mdma-renderer-vue     Vue 3 components
@mobile-reality/mdma-cli                   CLI prompt builder + validation
@mobile-reality/mdma-mcp                   MCP server for AI assistants

Getting Started

pnpm install
pnpm build
pnpm test

CLI

Interactive prompt builder for creating custom MDMA prompts.

# Run the prompt builder — opens a web app in your browser
npx @mobile-reality/mdma-cli

# Validate MDMA documents
npx @mobile-reality/mdma-cli validate "docs/**/*.md"
npx @mobile-reality/mdma-cli validate "docs/**/*.md" --fix  # auto-fix issues
npx @mobile-reality/mdma-cli validate "docs/**/*.md" --json # JSON output

The prompt builder walks you through:

1. Pick components — select from the 10 MDMA types (form, table, approval-gate, etc.)
2. Configure — define fields, options, roles, sensitive flags, and business rules
3. Set triggers — specify when the AI should generate MDMA components (keywords, contextual conditions)
4. Generate — an LLM creates a tailored customPrompt based on your configuration
5. Export — copy the result and use it in your app:

import { buildSystemPrompt } from '@mobile-reality/mdma-prompt-pack';

const systemPrompt = buildSystemPrompt({
  customPrompt: '<paste generated prompt here>',
});

Validator

Static analysis engine for MDMA documents. Validates structure, catches common LLM mistakes, and auto-fixes what it can.

import { validate } from '@mobile-reality/mdma-validator';

const result = validate(markdown);
// result.ok        — true if no unfixed errors
// result.issues    — all issues found
// result.output    — auto-fixed markdown
// result.fixCount  — number of issues auto-fixed

Rules

Every rule can be individually disabled via the exclude option:

const result = validate(markdown, {
  exclude: ['thinking-block', 'placeholder-content'],
});

Rule	Severity	Auto-fix	Description
yaml-correctness	error	--	YAML parses successfully. Detects and auto-splits multi-component blocks, strips --- separators LLMs insert.
field-name-typos	warning	--	Common field name mistakes: roles -> allowedRoles, onClick -> onAction, submit -> onSubmit.
schema-conformance	error	yes	Component type exists and data conforms to its Zod schema. Suggests closest type via fuzzy matching (e.g. "frm" -> did you mean "form"?) and lists all valid types.
duplicate-ids	error	yes	All component IDs are unique. Auto-fix appends -1, -2 suffixes.
id-format	warning	yes	IDs follow kebab-case (my-component-id). Auto-fix converts camelCase, snake_case, PascalCase and updates all references.
binding-syntax	error/warning	yes	{{binding}} expressions are well-formed. Catches empty {{ }}, extra whitespace {{ path }}, and single-brace {path}.
form-submit-action	error	--	Every type: form component declares a non-empty onSubmit action.
sensitive-flags	warning	yes	Form fields and table columns with PII-like names (email, phone, ssn, address, etc.) have sensitive: true. Supports custom PII patterns.
required-markers	info	--	Suggests required: true for fields named name, email, title, summary.
thinking-block	warning/info	--	If a thinking block is present, it should be the first component and only one should exist.
table-data-keys	warning	--	Data row keys match defined column keys. Flags extra keys and columns with no matching data.
select-options	warning	--	type: select fields have options defined as [{label, value}] objects.
chart-validation	warning	--	Chart CSV data has headers + data rows. xAxis/yAxis reference actual CSV column headers.
placeholder-content	info	--	Catches TODO, TBD, FIXME, ..., lorem ipsum in content fields.
flow-ordering	warning	--	Forward-only action references (targ