mdx-artifacts 0.1.1 → 0.2.0

package/dist/lib/react/registry.js

@@ -1,17 +1,53 @@
+const contentBlockGuidance = [
+    "Use title, badge, and summary for short visible display slots.",
+    "Use MDX children for long explanations, rationale, pros, cons, risks, and lists.",
+    "Do not invent Markdown heading parsers for slot names inside children."
+];
+const structuredRendererGuidance = [
+    "Keep domain data in explicit structured props.",
+    "Use ids for stable review anchors when the rendered block should be commentable.",
+    "Do not move code, diff rows, or line annotations into free-form prose children."
+];
+const layoutPrimitiveGuidance = [
+    "Use only when semantic components cannot express the arrangement.",
+    "Keep props focused on layout concerns such as spacing, ratios, collapse behavior, and surface treatment.",
+    "Do not encode workflow or domain semantics in layout wrappers."
+];
+const interactiveDataGuidance = [
+    "Use structured props for ids, labels, tags, and initial state.",
+    "Keep item fields short; do not put long prose or Markdown blocks into item records.",
+    "Persist user-controlled order or state through artifact interactions when available."
+];
+const exportEditorGuidance = [
+    "Keep handoff data in structured value or state props.",
+    "Use formats and titles for export UX, not for artifact domain modeling.",
+    "Prefer ExportPanel when an artifact needs to return decisions, edits, or comments to the workflow."
+];
+const reviewBoundaryGuidance = [
+    "Use stable ids for durable comment anchors.",
+    "Wrap the smallest meaningful review target, not decorative layout fragments.",
+    "Keep children as the visible content being reviewed."
+];
 export const componentRegistry = [
     {
         name: "InlineText",
         category: "content",
         stability: "stable",
-        description: "Renders short single-line text with controlled inline Markdown.",
+        authoring: { kind: "content-block", guidance: contentBlockGuidance },
+        description: "Renders children-first short single-line text with controlled inline Markdown.",
         useWhen: ["Titles", "Labels", "Captions", "Short notes", "Inline explanations"],
         props: [
+            {
+                name: "children",
+                type: "ReactNode",
+                contentType: "inlineMarkdown",
+                description: "Preferred short inline Markdown content."
+            },
             {
                 name: "text",
                 type: "string",
                 contentType: "inlineMarkdown",
-                required: true,
-                description: "Short text. Supports bold, emphasis, strikethrough, inline code, and links."
+                description: "Legacy short text prop. Prefer children for human-readable content."
             },
             {
                 name: "as",
@@ -24,25 +60,29 @@ export const componentRegistry = [
                 description: "Visual text variant."
             }
         ],
-        example: `<InlineText
-  as="h3"
-  variant="subtitle"
-  text="Use **MDX** as source and ~~raw HTML~~ only as fallback."
-/>`
+        example: `<InlineText as="h3" variant="subtitle">
+  Use **MDX** as source and ~~raw HTML~~ only as fallback.
+</InlineText>`
     },
     {
         name: "MarkdownBody",
         category: "content",
         stability: "stable",
-        description: "Renders controlled multi-line Markdown for component body copy.",
+        authoring: { kind: "content-block", guidance: contentBlockGuidance },
+        description: "Renders children-first controlled multi-line Markdown for component body copy.",
         useWhen: ["Component body explanations", "Controlled lists inside components", "Component-local prose"],
         props: [
+            {
+                name: "children",
+                type: "ReactNode",
+                contentType: "blockMarkdown",
+                description: "Preferred body content. Use MDX children for human-readable prose, lists, and local explanations."
+            },
             {
                 name: "body",
                 type: "string",
                 contentType: "blockMarkdown",
-                required: true,
-                description: "Multi-line Markdown. Supports headings, paragraphs, lists, blockquotes, bold, emphasis, strikethrough, inline code, and links. Use native MDX children inside Section for document-level prose."
+                description: "Legacy multi-line Markdown body prop. Prefer children for human-readable content. Supports headings, paragraphs, lists, blockquotes, bold, emphasis, strikethrough, inline code, and links."
             },
             {
                 name: "variant",
@@ -50,20 +90,353 @@ export const componentRegistry = [
                 description: "Body density variant."
             }
         ],
-        example: `<MarkdownBody
-  body={\`Use MarkdownBody when a component needs controlled body copy:
+        example: `<MarkdownBody>
+Use MarkdownBody when a component needs controlled body copy:
 
 - **Readable** paragraphs and lists
 - \\\`inline code\\\` for short technical names
 - Headings for local body sections
-- No tables, HTML, math, or code blocks\`}
+- No tables, HTML, math, or code blocks
+</MarkdownBody>`
+    },
+    {
+        name: "ContentItem",
+        category: "content",
+        stability: "stable",
+        authoring: { kind: "content-block", guidance: contentBlockGuidance },
+        description: "Renders one reusable content card with display slots, tone color, emphasis weight, and Markdown-rich body content.",
+        useWhen: ["Standalone content cards", "Recommendations", "Risks", "Highlights", "Reusable item blocks"],
+        props: [
+            {
+                name: "id",
+                type: "string",
+                contentType: "plainText",
+                description: "Optional stable anchor id for comments and state. Prefer short semantic ids such as risk.api-boundary."
+            },
+            {
+                name: "title",
+                type: "string",
+                contentType: "inlineMarkdown",
+                required: true,
+                description: "Primary visible label for this item."
+            },
+            {
+                name: "badge",
+                type: "string",
+                contentType: "plainText",
+                description: "Optional short visible label. Badge text does not choose color; tone controls color."
+            },
+            {
+                name: "summary",
+                type: "string",
+                contentType: "inlineMarkdown",
+                description: "Optional one-line summary. Use children for longer explanations and lists."
+            },
+            {
+                name: "icon",
+                type: "ReactNode",
+                description: "Optional decorative marker rendered in the component-defined title area. Emoji are recommended for agent-authored artifacts; project icon components may be passed when needed."
+            },
+            {
+                name: "tone",
+                type: "'neutral' | 'info' | 'positive' | 'warning' | 'danger' | 'accent'",
+                description: "Semantic color tone. Defaults to neutral."
+            },
+            {
+                name: "emphasis",
+                type: "'default' | 'primary' | 'subtle'",
+                description: "Structural visual weight. Defaults to default."
+            },
+            {
+                name: "children",
+                type: "ReactNode",
+                contentType: "blockMarkdown",
+                description: "Markdown-rich body content for rationale, lists, caveats, or supporting prose."
+            }
+        ],
+        example: `<ContentItem
+  id="item.component-first"
+  title="Component-first authoring"
+  badge="Recommended"
+  icon="✅"
+  tone="positive"
+  emphasis="primary"
+  summary="Best when the artifact needs stable interaction and visual structure."
+>
+  ### Tradeoffs
+
+  - Clear component boundaries
+  - Easy to debug
+  - Less natural than plain Markdown for long prose
+</ContentItem>`
+    },
+    {
+        name: "ContentSet",
+        category: "artifact",
+        stability: "stable",
+        authoring: { kind: "content-block", guidance: contentBlockGuidance },
+        description: "Groups same-kind content items in a grid or stack while preserving item-level tone, emphasis, and comment anchors.",
+        useWhen: ["Option groups", "Risk groups", "Recommendation sets", "Finding lists", "Comparable content cards"],
+        props: [
+            {
+                name: "id",
+                type: "string",
+                contentType: "plainText",
+                description: "Optional stable parent anchor id. Child item anchors become parentId.itemId when provided."
+            },
+            {
+                name: "title",
+                type: "string",
+                contentType: "inlineMarkdown",
+                required: true,
+                description: "Visible title for the content set."
+            },
+            {
+                name: "children",
+                type: "ReactNode",
+                required: true,
+                description: "Use ContentSet.Item children. Each item uses title, badge, summary, tone, emphasis, and Markdown body."
+            },
+            {
+                name: "icon",
+                type: "ReactNode",
+                description: "Optional decorative marker rendered beside the set title. It describes the group and is not inherited by items."
+            },
+            {
+                name: "layout",
+                type: "'grid' | 'stack'",
+                description: "Item arrangement. Defaults to grid."
+            },
+            {
+                name: "columns",
+                type: "2 | 3 | 4 | 5",
+                description: "Grid column count on desktop. Defaults to 3. Stack layout ignores this."
+            },
+            {
+                name: "surface",
+                type: "'plain' | 'subtle' | 'outlined'",
+                description: "Container surface treatment. Defaults to plain. Use outlined when the set should read as a bounded section."
+            },
+            {
+                name: "tone",
+                type: "'neutral' | 'info' | 'positive' | 'warning' | 'danger' | 'accent'",
+                description: "Optional default tone inherited by ContentSet.Item children."
+            },
+            {
+                name: "emphasis",
+                type: "'default' | 'primary' | 'subtle'",
+                description: "Optional default emphasis inherited by ContentSet.Item children."
+            }
+        ],
+        types: [
+            {
+                name: "ContentSet.Item",
+                description: "Compound child used inside ContentSet. It renders the same visual structure as ContentItem.",
+                fields: [
+                    {
+                        name: "id",
+                        type: "string",
+                        contentType: "plainText",
+                        description: "Optional stable child anchor id. When the parent has id, child anchors become parentId.itemId."
+                    },
+                    {
+                        name: "title",
+                        type: "string",
+                        contentType: "inlineMarkdown",
+                        required: true,
+                        description: "Primary visible item label."
+                    },
+                    {
+                        name: "badge",
+                        type: "string",
+                        contentType: "plainText",
+                        description: "Optional short visible label."
+                    },
+                    {
+                        name: "summary",
+                        type: "string",
+                        contentType: "inlineMarkdown",
+                        description: "Optional one-line summary. Use children for longer explanations and lists."
+                    },
+                    {
+                        name: "icon",
+                        type: "ReactNode",
+                        description: "Optional decorative marker rendered in the item title area. Use text props and tone for semantic meaning."
+                    },
+                    {
+                        name: "tone",
+                        type: "'neutral' | 'info' | 'positive' | 'warning' | 'danger' | 'accent'",
+                        description: "Optional item tone. Overrides the parent tone."
+                    },
+                    {
+                        name: "emphasis",
+                        type: "'default' | 'primary' | 'subtle'",
+                        description: "Optional item emphasis. Overrides the parent emphasis."
+                    },
+                    {
+                        name: "children",
+                        type: "ReactNode",
+                        contentType: "blockMarkdown",
+                        description: "Markdown-rich item body."
+                    }
+                ]
+            }
+        ],
+        example: `<ContentSet id="set.authoring-paths" title="Authoring paths" icon="🧭" layout="grid" columns={3} surface="subtle">
+  <ContentSet.Item
+    id="component-first"
+    title="Component-first"
+    badge="Recommended"
+    icon="✅"
+    tone="positive"
+    emphasis="primary"
+    summary="Best for stable interaction and visual structure."
+  >
+    ### Tradeoffs
+
+    - Clear component boundaries
+    - Easy to debug
+    - Less natural for long prose
+  </ContentSet.Item>
+</ContentSet>`
+    },
+    {
+        name: "SortableList",
+        category: "artifact",
+        stability: "stable",
+        authoring: { kind: "interactive-data", guidance: interactiveDataGuidance },
+        description: "Renders a draggable priority list from structured item data and persists the user-controlled order.",
+        useWhen: ["Priority sorting", "Ranked handoff tasks", "User-adjustable queues", "Structured ordering decisions"],
+        props: [
+            {
+                name: "id",
+                type: "string",
+                contentType: "plainText",
+                required: true,
+                description: "Stable interaction id used for review anchors and artifact state."
+            },
+            {
+                name: "title",
+                type: "string",
+                contentType: "inlineMarkdown",
+                required: true,
+                description: "Visible title for the sortable list."
+            },
+            {
+                name: "summary",
+                type: "string",
+                contentType: "inlineMarkdown",
+                description: "Optional one-line explanation for the sorting task."
+            },
+            {
+                name: "items",
+                type: "SortableListItem[]",
+                required: true,
+                description: "Structured item records. Keep fields short; use this component for interactive ordering, not long Markdown prose."
+            },
+            {
+                name: "surface",
+                type: "'plain' | 'subtle' | 'outlined'",
+                description: "Container surface treatment. Defaults to outlined."
+            }
+        ],
+        types: [
+            {
+                name: "SortableListItem",
+                description: "One short structured item in a SortableList.",
+                fields: [
+                    {
+                        name: "id",
+                        type: "string",
+                        contentType: "plainText",
+                        required: true,
+                        description: "Stable item id used in orderedIds exports."
+                    },
+                    {
+                        name: "title",
+                        type: "string",
+                        contentType: "inlineMarkdown",
+                        required: true,
+                        description: "Primary visible item label."
+                    },
+                    {
+                        name: "summary",
+                        type: "string",
+                        contentType: "inlineMarkdown",
+                        description: "Optional one-line item context."
+                    },
+                    {
+                        name: "badge",
+                        type: "string",
+                        contentType: "plainText",
+                        description: "Optional short priority or status label."
+                    },
+                    {
+                        name: "tags",
+                        type: "string[]",
+                        contentType: "json",
+                        description: "Optional short labels for filtering or scanning."
+                    },
+                    {
+                        name: "disabled",
+                        type: "boolean",
+                        description: "When true, the item is visible but cannot be moved by the user."
+                    }
+                ]
+            },
+            {
+                name: "SortableListInteraction",
+                description: "Persisted artifact interaction written after the user changes order.",
+                fields: [
+                    {
+                        name: "type",
+                        type: "'sortable-list'",
+                        required: true,
+                        description: "Interaction discriminator."
+                    },
+                    {
+                        name: "orderedIds",
+                        type: "string[]",
+                        required: true,
+                        description: "Current user-controlled item order."
+                    },
+                    {
+                        name: "orderedItems",
+                        type: "SortableListItem[]",
+                        required: true,
+                        description: "Current ordered item records for export handoff."
+                    }
+                ]
+            }
+        ],
+        example: `<SortableList
+  id="list.launch-priority"
+  title="Launch priority"
+  summary="Drag items or use the controls to change the handoff order."
+  items={[
+    {
+      id: "contentset-api",
+      title: "Stabilize ContentSet API",
+      summary: "Must land before public examples.",
+      badge: "P0",
+      tags: ["api", "docs"]
+    },
+    {
+      id: "layout-guidance",
+      title: "Clarify layout guidance",
+      summary: "Explain Frame, Columns, Section, and ContentSet boundaries.",
+      badge: "P1",
+      tags: ["protocol"]
+    }
+  ]}
 />`
     },
     {
         name: "CodeBlock",
         category: "content",
         stability: "stable",
-        description: "Renders code text with optional filename, language label, line numbers, and highlighted lines.",
+        authoring: { kind: "structured-renderer", guidance: structuredRendererGuidance },
+        description: "Renders code text with optional filename, language label, line numbers, copy control, and highlighted lines.",
         useWhen: ["Code examples", "Implementation notes", "Technical explanations", "Code review context"],
         props: [
             {
@@ -99,6 +472,11 @@ export const componentRegistry = [
                 name: "highlightLines",
                 type: "number[]",
                 description: "One-based line numbers to visually emphasize."
+            },
+            {
+                name: "copyable",
+                type: "boolean",
+                description: "Shows a copy button when true."
             }
         ],
         example: `<CodeBlock
@@ -116,6 +494,7 @@ export const componentRegistry = [
         name: "DiffBlock",
         category: "content",
         stability: "stable",
+        authoring: { kind: "structured-renderer", guidance: structuredRendererGuidance },
         description: "Renders structured diff lines with add, remove, and context rows plus a compact effective line number column.",
         useWhen: ["Code review context", "Patch explanations", "Before and after code changes", "Implementation reports"],
         props: [
@@ -191,6 +570,7 @@ export const componentRegistry = [
         name: "SeverityBadge",
         category: "semantic",
         stability: "stable",
+        authoring: { kind: "content-block", guidance: contentBlockGuidance },
         description: "Renders a compact severity, confidence, status, or risk label.",
         useWhen: ["Code review findings", "Risk labels", "Status summaries", "Annotated explanations"],
         props: [
@@ -212,7 +592,8 @@ export const componentRegistry = [
         name: "Callout",
         category: "semantic",
         stability: "stable",
-        description: "Highlights a focused note, warning, recommendation, or risk with controlled Markdown body copy.",
+        authoring: { kind: "content-block", guidance: contentBlockGuidance },
+        description: "Highlights a focused note, warning, recommendation, or risk with children-first Markdown body copy.",
         useWhen: ["Review notes", "Assumptions", "Warnings", "Implementation gotchas", "Recommendations"],
         props: [
             {
@@ -221,12 +602,17 @@ export const componentRegistry = [
                 contentType: "plainText",
                 description: "Optional stable anchor id for comments and state. Prefer short semantic ids such as callout.risk."
             },
+            {
+                name: "children",
+                type: "ReactNode",
+                contentType: "blockMarkdown",
+                description: "Preferred callout message content. Use MDX children for human-readable body copy."
+            },
             {
                 name: "body",
                 type: "string",
                 contentType: "blockMarkdown",
-                required: true,
-                description: "Controlled Markdown body. Use for the message inside the callout."
+                description: "Legacy controlled Markdown body prop. Prefer children for the message inside the callout."
             },
             {
                 name: "title",
@@ -240,17 +626,15 @@ export const componentRegistry = [
                 description: "Visual tone. Defaults to info."
             }
         ],
-        example: `<Callout
-  id="callout.review-focus"
-  tone="warning"
-  title="Review focus"
-  body="Check the **export path** before treating this artifact as complete."
-/>`
+        example: `<Callout id="callout.review-focus" tone="warning" title="Review focus">
+  Check the **export path** before treating this artifact as complete.
+</Callout>`
     },
     {
         name: "AnnotatedCode",
         category: "semantic",
         stability: "stable",
+        authoring: { kind: "structured-renderer", guidance: structuredRendererGuidance },
         description: "Combines a CodeBlock with line-level annotations and severity labels.",
         useWhen: ["Code explanations", "Review focus areas", "Implementation walkthroughs", "Risk notes tied to code lines"],
         props: [
@@ -356,6 +740,7 @@ export const componentRegistry = [
         name: "Stack",
         category: "layout",
         stability: "advanced",
+        authoring: { kind: "layout-primitive", guidance: layoutPrimitiveGuidance },
         description: "Arranges children in a single vertical column with controlled spacing and alignment.",
         useWhen: ["Advanced composition", "Vertical sections", "Storybook layout checks"],
         props: [
@@ -377,7 +762,7 @@ export const componentRegistry = [
             }
         ],
         example: `<Stack gap="md">
-  <MarkdownBody body="Use semantic components first." />
+  <MarkdownBody>Use semantic components first.</MarkdownBody>
   <ExportPanel value={{ status: "ready" }} />
 </Stack>`
     },
@@ -385,6 +770,7 @@ export const componentRegistry = [
         name: "Columns",
         category: "layout",
         stability: "advanced",
+        authoring: { kind: "layout-primitive", guidance: layoutPrimitiveGuidance },
         description: "Arranges children in ratio-based columns that collapse responsively.",
         useWhen: ["Advanced composition", "Main and supporting content", "Side-by-side artifact sections"],
         props: [
@@ -411,7 +797,7 @@ export const componentRegistry = [
             }
         ],
         example: `<Columns ratio="3:1" gap="md">
-  <MarkdownBody body="Main explanation." />
+  <MarkdownBody>Main explanation.</MarkdownBody>
   <Frame surface="subtle">Supporting notes</Frame>
 </Columns>`
     },
@@ -419,6 +805,7 @@ export const componentRegistry = [
         name: "Grid",
         category: "layout",
         stability: "advanced",
+        authoring: { kind: "layout-primitive", guidance: layoutPrimitiveGuidance },
         description: "Arranges children in equal-width two, three, or four column grids.",
         useWhen: ["Advanced composition", "Equal alternative cards", "Preview groups"],
         props: [
@@ -454,6 +841,7 @@ export const componentRegistry = [
         name: "SplitPane",
         category: "layout",
         stability: "advanced",
+        authoring: { kind: "layout-primitive", guidance: layoutPrimitiveGuidance },
         description: "Arranges children into a two-pane layout with a controlled ratio.",
         useWhen: ["Advanced composition", "Main content with sidebar", "Editor and preview layouts"],
         props: [
@@ -480,7 +868,7 @@ export const componentRegistry = [
             }
         ],
         example: `<SplitPane ratio="3:1">
-  <MarkdownBody body="Primary reading surface." />
+  <MarkdownBody>Primary reading surface.</MarkdownBody>
   <Frame surface="outlined">Sidebar</Frame>
 </SplitPane>`
     },
@@ -488,6 +876,7 @@ export const componentRegistry = [
         name: "Frame",
         category: "layout",
         stability: "advanced",
+        authoring: { kind: "layout-primitive", guidance: layoutPrimitiveGuidance },
         description: "Provides a stable visual boundary for previews, snippets, mockups, or charts.",
         useWhen: ["Advanced composition", "Preview boundaries", "Code or mockup framing"],
         props: [
@@ -509,13 +898,14 @@ export const componentRegistry = [
             }
         ],
         example: `<Frame surface="outlined" padding="md">
-  <MarkdownBody body="A framed preview." />
+  <MarkdownBody>A framed preview.</MarkdownBody>
 </Frame>`
     },
     {
         name: "CommentLayer",
         category: "artifact",
         stability: "stable",
+        authoring: { kind: "review-boundary", guidance: reviewBoundaryGuidance },
         description: "Provides local browser comment state for block-level artifact feedback. Artifact and Storybook shells provide this automatically.",
         useWhen: ["Custom React shells", "Reviewable artifacts", "Block-level user feedback", "Agent handoff comments"],
         props: [
@@ -529,7 +919,9 @@ export const componentRegistry = [
         example: `// Usually provided by the artifact shell.
 <CommentLayer>
   <CommentableBlock blockId="decision" title="Decision">
-    <DecisionMatrix question="Choose a path" options={[]} />
+    <ContentSet id="set.path" title="Choose a path" columns={2}>
+      <ContentSet.Item id="path-a" title="Path A">Readable option body.</ContentSet.Item>
+    </ContentSet>
   </CommentableBlock>
   <CommentExport />
 </CommentLayer>`
@@ -538,6 +930,7 @@ export const componentRegistry = [
         name: "Section",
         category: "artifact",
         stability: "stable",
+        authoring: { kind: "review-boundary", guidance: reviewBoundaryGuidance },
         description: "Defines a stable reviewable document section for native MDX prose.",
         useWhen: ["Reviewable native MDX prose", "Stable Markdown anchors", "Document structure", "Block-level feedback"],
         props: [
@@ -571,6 +964,7 @@ This section can contain native MDX paragraphs, lists, and code fences.
         name: "CommentableBlock",
         category: "artifact",
         stability: "stable",
+        authoring: { kind: "review-boundary", guidance: reviewBoundaryGuidance },
         description: "Wraps any artifact content with a stable block target and hover-revealed local comment input.",
         useWhen: ["Commenting on existing components", "Commenting on prose blocks", "Exporting block-level feedback"],
         props: [
@@ -604,15 +998,18 @@ This section can contain native MDX paragraphs, lists, and code fences.
         example: `<CommentableBlock
   blockId="component-menu"
   title="Component menu"
-  description="Feedback on the option grid"
+  description="Feedback on the content set"
 >
-  <OptionGrid title="Components" options={[]} />
+  <ContentSet id="set.components" title="Components">
+    <ContentSet.Item id="export-panel" title="ExportPanel">Readable item body.</ContentSet.Item>
+  </ContentSet>
 </CommentableBlock>`
     },
     {
         name: "CommentTarget",
         category: "artifact",
         stability: "stable",
+        authoring: { kind: "review-boundary", guidance: reviewBoundaryGuidance },
         description: "Marks a fine-grained comment target with hover affordance and persistent comment count.",
         useWhen: ["Component internals", "Fine-grained review targets", "Custom local component comment anchors"],
         props: [
@@ -651,6 +1048,7 @@ This section can contain native MDX paragraphs, lists, and code fences.
         name: "CommentExport",
         category: "artifact",
         stability: "stable",
+        authoring: { kind: "export-editor", guidance: exportEditorGuidance },
         description: "Compatibility dock for exporting comments from the nearest CommentLayer. Prefer ExportPanel when an artifact also has result output.",
         useWhen: ["Comments-only artifacts", "Legacy comment handoff", "Copying review comments without a result export"],
         props: [
@@ -709,110 +1107,13 @@ This section can contain native MDX paragraphs, lists, and code fences.
         example: `<CommentExport
   title="Export artifact feedback"
   formats={["markdown", "json"]}
-/>`
-    },
-    {
-        name: "DecisionMatrix",
-        category: "artifact",
-        stability: "stable",
-        description: "Compares options by pros, cons, risks, confidence, and recommendation.",
-        useWhen: ["Architecture decisions", "Product tradeoffs", "Implementation planning", "Open-source roadmap"],
-        props: [
-            {
-                name: "id",
-                type: "string",
-                contentType: "plainText",
-                description: "Optional stable anchor id for comments and state. Prefer short semantic ids such as decision.comment-targets."
-            },
-            {
-                name: "question",
-                type: "string",
-                contentType: "inlineMarkdown",
-                required: true,
-                description: "The decision question being answered."
-            },
-            {
-                name: "options",
-                type: "DecisionMatrixOption[]",
-                required: true,
-                description: "Options to compare. Each option can include name, pros, cons, risks, confidence, and verdict."
-            }
-        ],
-        types: [
-            {
-                name: "DecisionMatrixOption",
-                description: "One option in a decision comparison.",
-                fields: [
-                    {
-                        name: "id",
-                        type: "string",
-                        contentType: "plainText",
-                        description: "Optional stable child anchor id. When the parent has id, child anchors become parentId.optionId."
-                    },
-                    {
-                        name: "name",
-                        type: "string",
-                        contentType: "inlineMarkdown",
-                        required: true,
-                        description: "Option title."
-                    },
-                    {
-                        name: "summary",
-                        type: "string",
-                        contentType: "inlineMarkdown",
-                        description: "Short option summary."
-                    },
-                    {
-                        name: "pros",
-                        type: "string[]",
-                        contentType: "inlineMarkdown",
-                        description: "Advantages for this option."
-                    },
-                    {
-                        name: "cons",
-                        type: "string[]",
-                        contentType: "inlineMarkdown",
-                        description: "Disadvantages for this option."
-                    },
-                    {
-                        name: "risks",
-                        type: "string[]",
-                        contentType: "inlineMarkdown",
-                        description: "Risks or failure modes for this option."
-                    },
-                    {
-                        name: "confidence",
-                        type: "'low' | 'medium' | 'high'",
-                        description: "Confidence level for this option."
-                    },
-                    {
-                        name: "verdict",
-                        type: "string",
-                        contentType: "inlineMarkdown",
-                        description: "Short recommendation or conclusion for this option."
-                    }
-                ]
-            }
-        ],
-        example: `<DecisionMatrix
-  id="decision.stage-one"
-  question="Should the first stage focus on a Vite single HTML artifact?"
-  options={[
-    {
-      id: "vite",
-      name: "Vite single HTML artifact",
-      pros: ["Short feedback loop", "Direct component debugging"],
-      cons: ["No docs-site navigation yet"],
-      confidence: "high",
-      verdict: "Recommended for stage one"
-    }
-  ]}
 />`
     },
     {
         name: "ComparisonSet",
         category: "artifact",
         stability: "stable",
+        authoring: { kind: "content-block", guidance: contentBlockGuidance },
         description: "Groups comparable candidates while allowing each item to render arbitrary component content.",
         useWhen: ["Candidate comparison", "Mixed media alternatives", "Prototype comparison", "Reviewable option sets"],
         props: [
@@ -876,96 +1177,18 @@ This section can contain native MDX paragraphs, lists, and code fences.
         ],
         example: `<ComparisonSet id="comparison.artifact-forms" title="Compare artifact forms" columns={3}>
   <ComparisonSet.Item id="markdown" title="Markdown explanation" value="markdown">
-    <MarkdownBody body="Best for prose-heavy context." />
+    <MarkdownBody>Best for prose-heavy context.</MarkdownBody>
   </ComparisonSet.Item>
   <ComparisonSet.Item id="code" title="Code path" value="code">
     <Frame surface="subtle">Code renderer or local component</Frame>
   </ComparisonSet.Item>
 </ComparisonSet>`
-    },
-    {
-        name: "OptionGrid",
-        category: "artifact",
-        stability: "stable",
-        description: "Displays multiple options, component candidates, or prototype directions in a scannable grid.",
-        useWhen: ["Option exploration", "Component scope", "Prototype comparison"],
-        props: [
-            {
-                name: "id",
-                type: "string",
-                contentType: "plainText",
-                description: "Optional stable anchor id for comments and state. Prefer short semantic ids such as option.comment-flow."
-            },
-            {
-                name: "title",
-                type: "string",
-                contentType: "inlineMarkdown",
-                required: true,
-                description: "Grid title."
-            },
-            {
-                name: "options",
-                type: "OptionGridItem[]",
-                required: true,
-                description: "Items to display. Each item can include name, intent, description, and tradeoffs."
-            }
-        ],
-        types: [
-            {
-                name: "OptionGridItem",
-                description: "One option in an OptionGrid.",
-                fields: [
-                    {
-                        name: "id",
-                        type: "string",
-                        contentType: "plainText",
-                        description: "Optional stable child anchor id. When the parent has id, child anchors become parentId.itemId."
-                    },
-                    {
-                        name: "name",
-                        type: "string",
-                        contentType: "inlineMarkdown",
-                        required: true,
-                        description: "Option title."
-                    },
-                    {
-                        name: "intent",
-                        type: "string",
-                        contentType: "inlineMarkdown",
-                        description: "Short statement of what this option is trying to achieve."
-                    },
-                    {
-                        name: "description",
-                        type: "string",
-                        contentType: "inlineMarkdown",
-                        description: "Short option description."
-                    },
-                    {
-                        name: "tradeoffs",
-                        type: "string[]",
-                        contentType: "inlineMarkdown",
-                        description: "Tradeoffs or caveats for this option."
-                    }
-                ]
-            }
-        ],
-        example: `<OptionGrid
-  id="option.first-components"
-  title="First component scope"
-  options={[
-    {
-      id: "export",
-      name: "ExportPanel",
-      intent: "Return human edits to the workflow",
-      tradeoffs: ["Copy-only in v1", "Can add downloads later"]
-    }
-  ]}
-/>`
     },
     {
         name: "ExportPanel",
         category: "artifact",
         stability: "stable",
+        authoring: { kind: "export-editor", guidance: exportEditorGuidance },
         description: "Shows a floating export dock for artifact results and, when comments are available, review comments.",
         useWhen: ["Exporting decisions", "Copying state back to an agent", "Issue or PR handoff", "Configuration handoff", "Exporting comments with artifact results"],
         props: [
@@ -997,6 +1220,78 @@ This section can contain native MDX paragraphs, lists, and code fences.
 />`
     }
 ];
+const legacyComponentRegistry = [
+    {
+        name: "DecisionMatrix",
+        deprecated: {
+            replacement: "ContentSet",
+            guidance: [
+                "DecisionMatrix is kept only as a runtime compatibility shim for older MDX.",
+                "Use ContentSet with ContentSet.Item for new artifacts.",
+                "Existing MDX can still render, but validate will warn and guide migration."
+            ]
+        },
+        description: "Deprecated compatibility component. Use ContentSet with ContentSet.Item instead.",
+        useWhen: [],
+        props: [],
+        example: `<ContentSet id="decision.path" title="Choose the implementation path">
+  <ContentSet.Item id="path-a" title="Path A">Readable option body.</ContentSet.Item>
+</ContentSet>`
+    },
+    {
+        name: "DecisionMatrix.Option",
+        deprecated: {
+            replacement: "ContentSet.Item",
+            guidance: [
+                "DecisionMatrix.Option is kept only as a runtime compatibility shim for older MDX.",
+                "Use ContentSet.Item for new artifacts.",
+                "Move long pros, cons, risks, and rationale into MDX children."
+            ]
+        },
+        description: "Deprecated compatibility child component. Use ContentSet.Item instead.",
+        useWhen: [],
+        props: [],
+        example: `<ContentSet.Item id="path-a" title="Path A">
+  ### Tradeoffs
+
+  - Keep readable rationale in MDX children
+</ContentSet.Item>`
+    },
+    {
+        name: "OptionGrid",
+        deprecated: {
+            replacement: "ContentSet",
+            guidance: [
+                "OptionGrid is kept only as a runtime compatibility shim for older MDX.",
+                "Use ContentSet with ContentSet.Item for new artifacts.",
+                "Existing MDX can still render, but validate will warn and guide migration."
+            ]
+        },
+        description: "Deprecated compatibility component. Use ContentSet with ContentSet.Item instead.",
+        useWhen: [],
+        props: [],
+        example: `<ContentSet id="options.path" title="Implementation options">
+  <ContentSet.Item id="path-a" title="Path A">Readable option body.</ContentSet.Item>
+</ContentSet>`
+    },
+    {
+        name: "OptionGrid.Item",
+        deprecated: {
+            replacement: "ContentSet.Item",
+            guidance: [
+                "OptionGrid.Item is kept only as a runtime compatibility shim for older MDX.",
+                "Use ContentSet.Item for new artifacts.",
+                "Move long descriptions and tradeoffs into MDX children."
+            ]
+        },
+        description: "Deprecated compatibility child component. Use ContentSet.Item instead.",
+        useWhen: [],
+        props: [],
+        example: `<ContentSet.Item id="path-a" title="Path A">
+  Readable option body.
+</ContentSet.Item>`
+    }
+];
 export function findComponentMeta(name) {
-    return componentRegistry.find((component) => component.name.toLowerCase() === name.toLowerCase());
+    return [...componentRegistry, ...legacyComponentRegistry].find((component) => component.name.toLowerCase() === name.toLowerCase());
 }