@hex-core/components 1.7.0 → 1.8.1

package/dist/schemas.js

@@ -2984,7 +2984,7 @@ var tableSchema = {
 var dataTableSchema = {
   name: "data-table",
   displayName: "Data Table",
-  description: "Generic data-driven table built on TanStack Table + Hex UI Table primitives. Pass columns + data; add sorting/filtering/pagination via TanStack hooks.",
+  description: "Generic data-driven table built on TanStack Table + Hex Core Table primitives. Pass columns + data; add sorting/filtering/pagination via TanStack hooks.",
   category: "component",
   subcategory: "data",
   props: [
@@ -3468,7 +3468,7 @@ var commandSchema = {
       "Giving CommandItem non-unique values (breaks filtering and controlled state)",
       "Overriding CommandInput className to remove the border/padding \u2014 breaks the \u2318K icon layout",
       "Not rendering CommandEmpty \u2014 the list looks broken when a search has no matches",
-      "Querying CommandSeparator via cmdk's internal Separator state \u2014 Hex UI renders it as a presentational div with role='none' (and the `data-cmdk-separator` attribute preserved for selector compatibility) so it can sit inside CommandList's role=listbox without violating ARIA"
+      "Querying CommandSeparator via cmdk's internal Separator state \u2014 Hex Core renders it as a presentational div with role='none' (and the `data-cmdk-separator` attribute preserved for selector compatibility) so it can sit inside CommandList's role=listbox without violating ARIA"
     ],
     relatedComponents: ["combobox", "dialog", "dropdown-menu"],
     accessibilityNotes: "cmdk wires role=listbox/option and aria-activedescendant. Use the `label` prop on Command for a screen-reader-only name when no visible heading exists. CommandSeparator renders with role='none' (still selectable via `[data-cmdk-separator]`) so listbox-children rules are satisfied.",
@@ -6286,6 +6286,2213 @@ var codeBlockSchema = {
   tags: ["ai", "code", "shiki", "highlight", "copy", "rsc"]
 };
 
-export { accordionSchema, alertDialogSchema, alertSchema, aspectRatioSchema, attachmentSchema, avatarSchema, badgeSchema, breadcrumbSchema, buttonSchema, calendarSchema, cardSchema, checkboxSchema, citationSchema, clusterSchema, codeBlockSchema, collapsibleSchema, colorPickerSchema, comboboxSchema, commandSchema, composerSchema, containerSchema, contextMenuSchema, dataTableSchema, datePickerSchema, dialogSchema, drawerSchema, dropdownMenuSchema, dropzoneSchema, emptySchema, errorStateSchema, fileTreeSchema, formSchema, gridSchema, hoverCardSchema, inputOTPSchema, inputSchema, labelSchema, loadingIndicatorSchema, loadingSchema, markdownSchema, menubarSchema, messageActionsSchema, messageListSchema, messageSchema, multiComboboxSchema, navigationMenuSchema, paginationSchema, popoverSchema, progressSchema, radioGroupSchema, reasoningSchema, resizableSchema, scrollAreaSchema, selectSchema, separatorSchema, sheetSchema, sidebarSchema, skeletonSchema, sliderSchema, sonnerSchema, spacerSchema, stackSchema, stepperSchema, suggestionSchema, switchSchema, tableSchema, tabsSchema, tagSchema, textareaSchema, timePickerSchema, timelineSchema, toggleGroupSchema, toggleSchema, toolCallSchema, toolbarSchema, tooltipSchema, treeSchema };
+// src/artifacts/mind-map/mind-map.schema.ts
+var mindMapSchema = {
+  name: "mind-map",
+  displayName: "MindMap",
+  description: "Typed React mind map. Pass a hierarchical root node and the component lays children out radially (or horizontally) using d3-hierarchy's tree layout \u2014 no Mermaid string DSL required.",
+  category: "artifact",
+  subcategory: "hierarchy",
+  props: [
+    {
+      name: "root",
+      type: "object",
+      required: true,
+      description: "Hierarchy root: { id, label, children?, data? }. Children are laid out radially around the root."
+    },
+    {
+      name: "orientation",
+      type: "enum",
+      required: false,
+      default: "radial",
+      description: 'Layout direction \u2014 "radial" (children orbit the root) or "horizontal" (left-to-right tree).',
+      enumValues: ["radial", "horizontal"]
+    },
+    {
+      name: "width",
+      type: "number",
+      required: false,
+      default: 600,
+      description: "SVG pixel width."
+    },
+    {
+      name: "height",
+      type: "number",
+      required: false,
+      default: 400,
+      description: "SVG pixel height."
+    },
+    {
+      name: "onNodeClick",
+      type: "function",
+      required: false,
+      description: "Called with the clicked MindMapNode when a user clicks any node."
+    },
+    {
+      name: "className",
+      type: "string",
+      required: false,
+      description: "Additional CSS classes on the SVG element."
+    }
+  ],
+  variants: [],
+  slots: [],
+  dependencies: {
+    npm: ["clsx", "tailwind-merge"],
+    internal: ["lib/utils"],
+    peer: ["react", "react-dom"],
+    heavyPeer: [
+      {
+        name: "d3-hierarchy",
+        version: "^3.1.2",
+        bundleKbGzip: 3,
+        reason: "Computes the radial / horizontal tree layout; the component renders SVG with the result"
+      }
+    ]
+  },
+  tokensUsed: ["primary", "background", "foreground", "muted"],
+  examples: [
+    {
+      title: "Radial mind map",
+      description: "Default radial layout with three branches.",
+      code: '<MindMap root={{\n  id: "root",\n  label: "Project",\n  children: [\n    { id: "ui", label: "UI", children: [{ id: "btn", label: "Button" }] },\n    { id: "api", label: "API" },\n    { id: "db", label: "DB" },\n  ],\n}} />',
+      composition: ["mind-map", "hierarchy", "radial"]
+    },
+    {
+      title: "Horizontal mind map with click handler",
+      description: "Left-to-right tree useful for sidebars and detail panes.",
+      code: '<MindMap orientation="horizontal" onNodeClick={(n) => select(n.id)} root={data} />',
+      composition: ["mind-map", "horizontal", "interactive"]
+    }
+  ],
+  ai: {
+    whenToUse: "Visualize a typed hierarchy when you have structured data (not a Mermaid string) \u2014 concept maps, knowledge graphs, project decompositions, agent plan trees. Use radial when the root is conceptually central; horizontal when the hierarchy is left-to-right (file trees, decision trees).",
+    whenNotToUse: "Don't use for free-form node graphs with arbitrary edges (use Canvas with reactflow). Don't use to render Mermaid markdown from agents (use Diagram). Don't use for hierarchies sized by value (use TreeMap or Sunburst).",
+    commonMistakes: [
+      "Passing an unmemoized `root` object on every render \u2014 the layout pass re-runs and node positions thrash. Memoize",
+      "Sizing the SVG to 0 (no explicit width/height and no parent layout) \u2014 the layout returns degenerate coordinates",
+      "Mutating the root hierarchy in place between renders \u2014 d3-hierarchy mutates its own internal tree, but the input object should be treated as immutable"
+    ],
+    relatedComponents: ["tree-map", "org-chart", "sunburst", "dendrogram", "canvas", "diagram"],
+    accessibilityNotes: 'The SVG carries role="img" with a <title> and <desc> summarizing the node count and root label. For agent outputs, also expose a parallel text representation (a nested <ul> of node labels in a <details>) so screen-reader users get the structure.',
+    tokenBudget: 320
+  },
+  tags: ["artifact", "diagram", "mind-map", "hierarchy", "tree", "radial"]
+};
+
+// src/artifacts/tree-map/tree-map.schema.ts
+var treeMapSchema = {
+  name: "tree-map",
+  displayName: "TreeMap",
+  description: "Nested rectangles sized by value \u2014 each leaf's area is proportional to its `value`. Squarified by default for legibility.",
+  category: "artifact",
+  subcategory: "hierarchy",
+  props: [
+    {
+      name: "root",
+      type: "object",
+      required: true,
+      description: "Hierarchy root: { id, label, value?, children? }. Leaves require a positive `value`; internal nodes are summed."
+    },
+    {
+      name: "width",
+      type: "number",
+      required: false,
+      default: 600,
+      description: "SVG pixel width."
+    },
+    {
+      name: "height",
+      type: "number",
+      required: false,
+      default: 400,
+      description: "SVG pixel height."
+    },
+    {
+      name: "padding",
+      type: "number",
+      required: false,
+      default: 2,
+      description: "Inner padding between sibling rectangles, in pixels."
+    },
+    {
+      name: "tile",
+      type: "enum",
+      required: false,
+      default: "squarify",
+      description: 'Tiling algorithm \u2014 "squarify" keeps rectangles close to square; "binary" is faster; "slice-dice" alternates direction by depth.',
+      enumValues: ["squarify", "binary", "slice-dice"]
+    },
+    {
+      name: "colorBy",
+      type: "enum",
+      required: false,
+      default: "depth",
+      description: 'Fill strategy \u2014 "depth" cycles palette tokens, "value" interpolates the primary token by value, or pass a (node, depth) => string.',
+      enumValues: ["depth", "value"]
+    },
+    {
+      name: "onLeafClick",
+      type: "function",
+      required: false,
+      description: "Called with the clicked TreeMapNode when a user clicks any leaf."
+    },
+    {
+      name: "className",
+      type: "string",
+      required: false,
+      description: "Additional CSS classes on the SVG element."
+    }
+  ],
+  variants: [],
+  slots: [],
+  dependencies: {
+    npm: ["clsx", "tailwind-merge"],
+    internal: ["lib/utils"],
+    peer: ["react", "react-dom"],
+    heavyPeer: [
+      {
+        name: "d3-hierarchy",
+        version: "^3.1.2",
+        bundleKbGzip: 3,
+        reason: "Computes the squarified treemap layout; the component renders SVG rectangles with the result"
+      }
+    ]
+  },
+  tokensUsed: ["primary", "accent", "secondary", "muted", "background", "foreground"],
+  examples: [
+    {
+      title: "File-size treemap",
+      description: "Visualize the relative size of files in a folder.",
+      code: '<TreeMap root={{\n  id: "root", label: "src",\n  children: [\n    { id: "a", label: "app", value: 240 },\n    { id: "l", label: "lib", value: 90 },\n    { id: "t", label: "tests", value: 120 },\n  ],\n}} />',
+      composition: ["tree-map", "hierarchy", "value-scaled"]
+    },
+    {
+      title: "Heatmap-style coloring by value",
+      description: "Use the value-interpolated palette to highlight outliers.",
+      code: '<TreeMap colorBy="value" root={budgetTree} />',
+      composition: ["tree-map", "heatmap"]
+    }
+  ],
+  ai: {
+    whenToUse: 'Compare relative sizes inside a hierarchy \u2014 file sizes, budgets, market caps, allocations. Use when the user cares about "which slice of the whole is biggest" and the hierarchy is at most 2\u20133 levels deep.',
+    whenNotToUse: "Don't use to show edges/relationships (use MindMap or Canvas). Don't use for time series (use a chart). Don't use when leaves all have similar values \u2014 area differences become invisible.",
+    commonMistakes: [
+      "Leaf values that don't sum to the parent \u2014 d3-hierarchy aggregates leaves; internal-node `value` props are ignored when children exist",
+      "Negative or zero leaf values \u2014 produce zero-area rectangles or NaN positions. Filter or clamp upstream",
+      "Passing the same root reference but mutating its children in place \u2014 React skips the re-layout. Provide a new root object on data change"
+    ],
+    relatedComponents: ["mind-map", "sunburst", "org-chart", "dendrogram", "diagram"],
+    accessibilityNotes: 'The SVG carries role="img" with a <title> and <desc> summarizing the leaf count and root label. For large or interactive treemaps, also expose a parallel <table> of label/value pairs for screen readers.',
+    tokenBudget: 320
+  },
+  tags: ["artifact", "diagram", "tree-map", "hierarchy", "area", "squarify"]
+};
+
+// src/artifacts/org-chart/org-chart.schema.ts
+var orgChartSchema = {
+  name: "org-chart",
+  displayName: "OrgChart",
+  description: "Top-down organizational chart with collapsible subtrees. Each node renders as a rounded card showing label + subtitle; click any node with children to fold its subtree behind a +N badge.",
+  category: "artifact",
+  subcategory: "hierarchy",
+  props: [
+    {
+      name: "root",
+      type: "object",
+      required: true,
+      description: "Hierarchy root: { id, label, subtitle?, avatarUrl?, children? }."
+    },
+    {
+      name: "collapsible",
+      type: "boolean",
+      required: false,
+      default: true,
+      description: "When true, clicking a node with children toggles its collapsed state."
+    },
+    {
+      name: "defaultExpandedDepth",
+      type: "number",
+      required: false,
+      description: "Nodes deeper than this depth render collapsed initially. Defaults to Infinity (all expanded)."
+    },
+    {
+      name: "nodeWidth",
+      type: "number",
+      required: false,
+      default: 180,
+      description: "Pixel width of each node card."
+    },
+    {
+      name: "nodeHeight",
+      type: "number",
+      required: false,
+      default: 64,
+      description: "Pixel height of each node card."
+    },
+    {
+      name: "width",
+      type: "number",
+      required: false,
+      default: 800,
+      description: "SVG pixel width."
+    },
+    {
+      name: "height",
+      type: "number",
+      required: false,
+      default: 480,
+      description: "SVG pixel height."
+    },
+    {
+      name: "onNodeClick",
+      type: "function",
+      required: false,
+      description: "Called with the clicked OrgNode. Fires before any internal collapse toggle."
+    },
+    {
+      name: "className",
+      type: "string",
+      required: false,
+      description: "Additional CSS classes on the SVG element."
+    }
+  ],
+  variants: [],
+  slots: [],
+  dependencies: {
+    npm: ["clsx", "tailwind-merge"],
+    internal: ["lib/utils"],
+    peer: ["react", "react-dom"],
+    heavyPeer: [
+      {
+        name: "d3-hierarchy",
+        version: "^3.1.2",
+        bundleKbGzip: 3,
+        reason: "Computes the top-down tree layout; the component renders SVG node cards with the result"
+      }
+    ]
+  },
+  tokensUsed: ["card", "border", "foreground", "muted-foreground", "primary", "primary-foreground", "background"],
+  examples: [
+    {
+      title: "Three-level org chart",
+      description: "CEO with two reports, one of whom has further reports.",
+      code: '<OrgChart root={{\n  id: "ceo", label: "Jane Doe", subtitle: "CEO",\n  children: [\n    { id: "cto", label: "Bob Smith", subtitle: "CTO",\n      children: [{ id: "eng", label: "Eng Team", subtitle: "12 people" }] },\n    { id: "cfo", label: "Sara Lin", subtitle: "CFO" },\n  ],\n}} />',
+      composition: ["org-chart", "hierarchy", "people"]
+    },
+    {
+      title: "Initially collapsed past depth 1",
+      description: "Render only the top two layers expanded; click +N badges to drill down.",
+      code: "<OrgChart defaultExpandedDepth={1} root={orgTree} />",
+      composition: ["org-chart", "collapsible"]
+    }
+  ],
+  ai: {
+    whenToUse: "Visualize people / team / department hierarchies, or any tree where each node is a labeled entity (not a value-sized bucket). Use when relationships are strictly parent-child and the user wants to drill into branches. `onNodeClick` fires for ALL nodes (root, internal, leaves) BEFORE the internal collapse toggle so consumers can observe pre-toggle state.",
+    whenNotToUse: "Don't use for value-scaled hierarchies (use TreeMap or Sunburst). Don't use for arbitrary node graphs with cross-edges (use Canvas). Don't use for purely conceptual maps (use MindMap).",
+    commonMistakes: [
+      "Hierarchies thousands of nodes deep \u2014 d3.tree's horizontal spread becomes unreadable. Combine with `defaultExpandedDepth` and let users drill",
+      "Mutating `root` in place when toggling expansion externally \u2014 internal collapse state keys off ids, so the controlled escape hatch should provide a stable id and a NEW root object",
+      "Placing the SVG in a 0\xD70 container \u2014 the layout computes from `width`/`height`, but the rendered SVG inherits its container's dimensions"
+    ],
+    relatedComponents: ["mind-map", "tree-map", "sunburst", "dendrogram", "canvas", "diagram"],
+    accessibilityNotes: 'The SVG carries role="img" with a <title> and <desc> summarizing the visible node count and root label. Collapsed-count badges are visual; for screen readers, also expose a parallel <ul> listing label/subtitle/depth.',
+    tokenBudget: 360
+  },
+  tags: ["artifact", "diagram", "org-chart", "hierarchy", "tree", "people"]
+};
+
+// src/artifacts/sunburst/sunburst.schema.ts
+var sunburstSchema = {
+  name: "sunburst",
+  displayName: "Sunburst",
+  description: "Radial hierarchy by value. Each ring is a deeper level of the tree; segment angles are proportional to summed values. Click a segment to drill in; click the center to zoom out.",
+  category: "artifact",
+  subcategory: "hierarchy",
+  props: [
+    {
+      name: "root",
+      type: "object",
+      required: true,
+      description: "Hierarchy root: { id, label, value?, children? }. Leaves require a positive `value`; internal nodes are summed."
+    },
+    {
+      name: "drillable",
+      type: "boolean",
+      required: false,
+      default: true,
+      description: "When true, clicking a segment with children focuses it as the new center. Click the center to zoom back out."
+    },
+    {
+      name: "centerLabel",
+      type: "ReactNode",
+      required: false,
+      description: "Optional content rendered at the SVG center (e.g. a total). Falls back to the focused node's label."
+    },
+    {
+      name: "size",
+      type: "number",
+      required: false,
+      default: 400,
+      description: "Pixel size of the rendered SVG (it's square)."
+    },
+    {
+      name: "onSegmentClick",
+      type: "function",
+      required: false,
+      description: "Called with the clicked SunburstNode. Fires before any internal drill."
+    },
+    {
+      name: "className",
+      type: "string",
+      required: false,
+      description: "Additional CSS classes on the SVG element."
+    }
+  ],
+  variants: [],
+  slots: [],
+  dependencies: {
+    npm: ["clsx", "tailwind-merge"],
+    internal: ["lib/utils"],
+    peer: ["react", "react-dom"],
+    heavyPeer: [
+      {
+        name: "d3-hierarchy",
+        version: "^3.1.2",
+        bundleKbGzip: 3,
+        reason: "Computes the partition layout that positions each ring segment"
+      },
+      {
+        name: "d3-shape",
+        version: "^3.2.0",
+        bundleKbGzip: 6,
+        reason: "Generates the SVG arc path for each segment"
+      }
+    ]
+  },
+  tokensUsed: ["primary", "accent", "secondary", "muted", "card", "border", "foreground", "background"],
+  examples: [
+    {
+      title: "Two-level sunburst",
+      description: "Visualize a portfolio split with sub-allocations.",
+      code: '<Sunburst root={{\n  id: "root", label: "Portfolio",\n  children: [\n    { id: "eq", label: "Equity", children: [\n      { id: "us", label: "US", value: 60 },\n      { id: "intl", label: "Intl", value: 20 },\n    ]},\n    { id: "fx", label: "Fixed Income", value: 20 },\n  ],\n}} />',
+      composition: ["sunburst", "hierarchy", "value-scaled"]
+    },
+    {
+      title: "Custom center label with totals",
+      description: "Use centerLabel to show the sum or other context.",
+      code: "<Sunburst centerLabel={<strong>$1.2M</strong>} root={portfolio} />",
+      composition: ["sunburst", "center-label"]
+    }
+  ],
+  ai: {
+    whenToUse: "Visualize a value-scaled hierarchy where the user wants to see both the parent share and child sub-shares at once \u2014 portfolio allocations, time spent by category \xD7 subcategory, file system disk usage. Drill-down lets users focus a branch. `onSegmentClick` fires for ALL segments BEFORE the internal drill so consumers can observe pre-drill focus.",
+    whenNotToUse: "Don't use for hierarchies without meaningful values per leaf (use MindMap or OrgChart). Don't use for >4 levels \u2014 outer rings become unreadable. Don't use for arbitrary node-edge graphs (use Canvas).",
+    commonMistakes: [
+      "Leaf values that don't sum at internal nodes \u2014 d3-hierarchy aggregates leaves; internal-node `value` props are ignored when children exist",
+      "Negative or zero leaf values \u2014 produce zero-width arcs or NaN angles. Filter or clamp upstream",
+      "Forgetting the resetting effect \u2014 when the parent updates `root` to a different tree, the focused id may no longer exist; the component re-syncs to the new root automatically"
+    ],
+    relatedComponents: ["tree-map", "mind-map", "org-chart", "dendrogram", "diagram"],
+    accessibilityNotes: 'The SVG carries role="img" with a <title> and <desc> summarizing segment count and focused node. Drill-down is mouse-only by default; expose a parallel <table> or breadcrumb for keyboard / screen-reader users.',
+    tokenBudget: 360
+  },
+  tags: ["artifact", "diagram", "sunburst", "hierarchy", "radial", "value-scaled"]
+};
+
+// src/artifacts/dendrogram/dendrogram.schema.ts
+var dendrogramSchema = {
+  name: "dendrogram",
+  displayName: "Dendrogram",
+  description: "Clustering tree where every leaf sits at the same depth, regardless of branch length \u2014 the visual signature of taxonomies, phylogenetic trees, and hierarchical-clustering output.",
+  category: "artifact",
+  subcategory: "hierarchy",
+  props: [
+    {
+      name: "root",
+      type: "object",
+      required: true,
+      description: "Hierarchy root: { id, label, children? }."
+    },
+    {
+      name: "orientation",
+      type: "enum",
+      required: false,
+      default: "horizontal",
+      description: '"horizontal" runs root-to-leaves left\u2192right; "vertical" runs top\u2192bottom.',
+      enumValues: ["horizontal", "vertical"]
+    },
+    {
+      name: "linkShape",
+      type: "enum",
+      required: false,
+      default: "step",
+      description: '"step" draws right-angle elbow links (taxonomy aesthetic); "diagonal" uses smooth Bezier curves.',
+      enumValues: ["step", "diagonal"]
+    },
+    {
+      name: "width",
+      type: "number",
+      required: false,
+      default: 600,
+      description: "SVG pixel width."
+    },
+    {
+      name: "height",
+      type: "number",
+      required: false,
+      default: 400,
+      description: "SVG pixel height."
+    },
+    {
+      name: "onLeafClick",
+      type: "function",
+      required: false,
+      description: "Called with the clicked DendrogramNode when a user clicks any leaf."
+    },
+    {
+      name: "className",
+      type: "string",
+      required: false,
+      description: "Additional CSS classes on the SVG element."
+    }
+  ],
+  variants: [],
+  slots: [],
+  dependencies: {
+    npm: ["clsx", "tailwind-merge"],
+    internal: ["lib/utils"],
+    peer: ["react", "react-dom"],
+    heavyPeer: [
+      {
+        name: "d3-hierarchy",
+        version: "^3.1.2",
+        bundleKbGzip: 3,
+        reason: "Computes the cluster layout (equal-depth leaves) used to position nodes"
+      }
+    ]
+  },
+  tokensUsed: ["primary", "muted-foreground", "foreground", "background"],
+  examples: [
+    {
+      title: "Taxonomy dendrogram",
+      description: "Equal-depth leaves arranged horizontally with step links.",
+      code: '<Dendrogram root={{\n  id: "root", label: "Animals",\n  children: [\n    { id: "mammals", label: "Mammals", children: [\n      { id: "cat", label: "Cat" },\n      { id: "dog", label: "Dog" },\n    ]},\n    { id: "birds", label: "Birds", children: [{ id: "robin", label: "Robin" }] },\n  ],\n}} />',
+      composition: ["dendrogram", "hierarchy", "taxonomy"]
+    },
+    {
+      title: "Vertical dendrogram with diagonal links",
+      description: "Top-down orientation with smooth Bezier links.",
+      code: '<Dendrogram orientation="vertical" linkShape="diagonal" root={tree} />',
+      composition: ["dendrogram", "vertical", "diagonal"]
+    }
+  ],
+  ai: {
+    whenToUse: "Visualize taxonomic / phylogenetic / clustering hierarchies where the user expects every leaf to sit at the same depth. Ideal when the tree shape itself is the message (groupings, sibling relationships). `onLeafClick` fires for LEAVES ONLY \u2014 internal-node clicks are no-ops (use OrgChart if you need callbacks on every node).",
+    whenNotToUse: "Don't use for value-scaled hierarchies (use TreeMap or Sunburst). Don't use for tree shapes where depth has meaning (use OrgChart, which uses d3.tree). Don't use for arbitrary node graphs (use Canvas).",
+    commonMistakes: [
+      "Confusing dendrogram with org chart \u2014 dendrogram aligns ALL leaves at a single edge regardless of branch depth, which is wrong for org structures where reporting depth is meaningful",
+      "Hundreds of leaves on a fixed-size SVG \u2014 leaves overlap. Either grow the SVG or paginate the tree",
+      "Mutating the root object in place \u2014 the layout pass treats input as immutable; always provide a new root reference on data change"
+    ],
+    relatedComponents: ["mind-map", "tree-map", "org-chart", "sunburst", "diagram"],
+    accessibilityNotes: 'The SVG carries role="img" with a <title> and <desc> summarizing the leaf count and root label. For agent outputs, expose a parallel <ul> grouping leaves by their parent so screen-reader users get the clustering structure.',
+    tokenBudget: 320
+  },
+  tags: ["artifact", "diagram", "dendrogram", "hierarchy", "cluster", "taxonomy"]
+};
+
+// src/artifacts/sankey/sankey.schema.ts
+var sankeySchema = {
+  name: "sankey",
+  displayName: "Sankey",
+  description: 'Weighted-flow diagram. Nodes arranged in horizontal columns by topological depth; link thickness encodes flow value. Use for funnels, energy/material/money flows, and any "value moving from A to B" picture.',
+  category: "artifact",
+  subcategory: "flow",
+  props: [
+    {
+      name: "nodes",
+      type: "object",
+      required: true,
+      description: "Array of { id, label }. Every link's source/target MUST match an id here."
+    },
+    {
+      name: "links",
+      type: "object",
+      required: true,
+      description: "Array of { source, target, value }. Values must be positive."
+    },
+    {
+      name: "width",
+      type: "number",
+      required: false,
+      default: 720,
+      description: "SVG pixel width."
+    },
+    {
+      name: "height",
+      type: "number",
+      required: false,
+      default: 420,
+      description: "SVG pixel height."
+    },
+    {
+      name: "nodeAlign",
+      type: "enum",
+      required: false,
+      default: "justify",
+      description: "Column alignment strategy.",
+      enumValues: ["left", "right", "center", "justify"]
+    },
+    {
+      name: "nodeWidth",
+      type: "number",
+      required: false,
+      default: 12,
+      description: "Pixel width of each node rectangle."
+    },
+    {
+      name: "nodePadding",
+      type: "number",
+      required: false,
+      default: 8,
+      description: "Vertical pixel gap between nodes in the same column."
+    },
+    {
+      name: "onLinkHover",
+      type: "function",
+      required: false,
+      description: "Called with the hovered SankeyLink (or null when hover ends)."
+    },
+    {
+      name: "onNodeClick",
+      type: "function",
+      required: false,
+      description: "Called with the clicked SankeyNode."
+    },
+    {
+      name: "className",
+      type: "string",
+      required: false,
+      description: "Additional CSS classes on the SVG element."
+    }
+  ],
+  variants: [],
+  slots: [],
+  dependencies: {
+    npm: ["clsx", "tailwind-merge"],
+    internal: ["lib/utils"],
+    peer: ["react", "react-dom"],
+    heavyPeer: [
+      {
+        name: "d3-sankey",
+        version: "^0.12.3",
+        bundleKbGzip: 6,
+        reason: "Computes the column layout and link routing; the component renders SVG with the result"
+      }
+    ]
+  },
+  tokensUsed: ["primary", "background", "foreground", "muted"],
+  examples: [
+    {
+      title: "Energy flow",
+      description: "Two sources flowing into a single sink.",
+      code: '<Sankey\n  nodes={[\n    { id: "coal", label: "Coal" },\n    { id: "gas", label: "Gas" },\n    { id: "grid", label: "Grid" },\n  ]}\n  links={[\n    { source: "coal", target: "grid", value: 60 },\n    { source: "gas", target: "grid", value: 30 },\n  ]}\n/>',
+      composition: ["sankey", "flow", "energy"]
+    },
+    {
+      title: "Funnel-style with hover",
+      description: "Surface link details on hover for tooltips.",
+      code: "<Sankey\n  nodes={steps}\n  links={transitions}\n  onLinkHover={(l) => setActive(l)}\n/>",
+      composition: ["sankey", "interactive", "tooltip"]
+    }
+  ],
+  ai: {
+    whenToUse: "Visualize how a quantity is distributed and re-distributed across a multi-step pipeline \u2014 energy mix, marketing-funnel transitions, traffic referral flows, budget allocation by department \xD7 line-item. The thicker the link, the more value moves along it.",
+    whenNotToUse: "Don't use for hierarchies (use TreeMap or Sunburst). Don't use for arbitrary node-edge graphs without a clear left-to-right flow (use Canvas). Don't use when total flow doesn't conserve from column to column \u2014 d3-sankey assumes a balanced graph.",
+    commonMistakes: [
+      "A link's source or target id not present in `nodes` \u2014 d3-sankey throws an opaque error. Validate ids upstream",
+      "Negative or zero `value` \u2014 produces zero-width or NaN-positioned links. Filter or clamp upstream",
+      "Cycles in the link graph \u2014 d3-sankey requires a DAG. If your data has feedback loops, collapse them or split into multiple Sankeys",
+      "Mutating the input `nodes` / `links` between renders \u2014 the component clones internally to protect consumer arrays, but unmemoized inputs still trigger a full re-layout each render. Memoize"
+    ],
+    relatedComponents: ["funnel", "pyramid", "flowchart", "canvas", "diagram"],
+    accessibilityNotes: 'The SVG carries role="img" with a <title> and <desc> summarizing node and link counts. For agent outputs, also expose a parallel <table> of source / target / value triples so screen-reader users get the flow magnitudes.',
+    tokenBudget: 360
+  },
+  tags: ["artifact", "diagram", "sankey", "flow", "weighted", "funnel"]
+};
+
+// src/artifacts/funnel/funnel.schema.ts
+var funnelSchema = {
+  name: "funnel",
+  displayName: "Funnel",
+  description: "Conversion funnel \u2014 vertical stack of trapezoidal stages whose width is proportional to each stage's value. Pure SVG; no heavy peer dep.",
+  category: "artifact",
+  subcategory: "flow",
+  props: [
+    {
+      name: "stages",
+      type: "object",
+      required: true,
+      description: "Ordered top-to-bottom array of { id, label, value }. Values must be non-negative."
+    },
+    {
+      name: "width",
+      type: "number",
+      required: false,
+      default: 480,
+      description: "SVG pixel width."
+    },
+    {
+      name: "height",
+      type: "number",
+      required: false,
+      default: 360,
+      description: "SVG pixel height."
+    },
+    {
+      name: "gap",
+      type: "number",
+      required: false,
+      default: 4,
+      description: "Pixel gap between stages."
+    },
+    {
+      name: "showConversion",
+      type: "boolean",
+      required: false,
+      default: true,
+      description: "Show stage-to-stage conversion percentages alongside the funnel."
+    },
+    {
+      name: "onStageClick",
+      type: "function",
+      required: false,
+      description: "Called with the clicked FunnelStage."
+    },
+    {
+      name: "className",
+      type: "string",
+      required: false,
+      description: "Additional CSS classes on the SVG element."
+    }
+  ],
+  variants: [],
+  slots: [],
+  dependencies: {
+    npm: ["clsx", "tailwind-merge"],
+    internal: ["lib/utils"],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: ["primary", "primary-foreground", "muted-foreground", "background"],
+  examples: [
+    {
+      title: "Signup funnel",
+      description: "Standard top-of-funnel \u2192 conversion drop-off.",
+      code: '<Funnel stages={[\n  { id: "visit", label: "Visited", value: 10000 },\n  { id: "signup", label: "Signed up", value: 1200 },\n  { id: "active", label: "Active", value: 480 },\n  { id: "paid", label: "Paid", value: 95 },\n]} />',
+      composition: ["funnel", "conversion", "stages"]
+    },
+    {
+      title: "Click stages to drill in",
+      description: "Wire onStageClick to a route or modal for stage detail.",
+      code: "<Funnel stages={data} onStageClick={(s) => router.push(`/stages/${s.id}`)} />",
+      composition: ["funnel", "interactive"]
+    }
+  ],
+  ai: {
+    whenToUse: "Visualize linear conversion drop-off \u2014 onboarding step completion, marketing-funnel rates, sales pipeline stages, ETL row counts. Use when each stage is a strict subset of the previous and the magnitude of the drop is the message.",
+    whenNotToUse: "Don't use for non-monotonic data where a later stage can exceed an earlier one (use a column chart). Don't use for branching funnels where flow splits across paths (use Sankey). Don't use for ranked categorical data without a flow concept (use Pyramid).",
+    commonMistakes: [
+      `Stage values that aren't monotonically non-increasing \u2014 visually misleads users into thinking the funnel "recovers". Validate upstream`,
+      "Negative values \u2014 produce zero-width stages or NaN positions. Filter or clamp upstream",
+      "More than ~8 stages \u2014 labels become unreadable. Group adjacent stages or use Sankey"
+    ],
+    relatedComponents: ["sankey", "pyramid", "flowchart", "diagram"],
+    accessibilityNotes: 'The SVG carries role="img" with a <title> and <desc> summarizing stage count and peak value. For agent outputs, also expose a parallel <table> of label/value/conversion-rate triples so screen-reader users get the magnitudes.',
+    tokenBudget: 280
+  },
+  tags: ["artifact", "diagram", "funnel", "conversion", "flow"]
+};
+
+// src/artifacts/pyramid/pyramid.schema.ts
+var pyramidSchema = {
+  name: "pyramid",
+  displayName: "Pyramid",
+  description: "Ranked-tier pyramid. Tiers stack top-to-bottom; widths can grow toward the base (widening) or shrink (narrowing). Pure SVG; no heavy peer dep. Distinct from Funnel \u2014 Pyramid encodes RANK, Funnel encodes FLOW.",
+  category: "artifact",
+  subcategory: "flow",
+  props: [
+    {
+      name: "tiers",
+      type: "object",
+      required: true,
+      description: "Ordered top-to-bottom array of { id, label, value? }. The first entry is the apex."
+    },
+    {
+      name: "shape",
+      type: "enum",
+      required: false,
+      default: "widening",
+      description: 'Tier-width direction \u2014 "widening" grows toward the base; "narrowing" shrinks toward it.',
+      enumValues: ["widening", "narrowing"]
+    },
+    {
+      name: "width",
+      type: "number",
+      required: false,
+      default: 480,
+      description: "SVG pixel width."
+    },
+    {
+      name: "height",
+      type: "number",
+      required: false,
+      default: 360,
+      description: "SVG pixel height."
+    },
+    {
+      name: "gap",
+      type: "number",
+      required: false,
+      default: 4,
+      description: "Pixel gap between tiers."
+    },
+    {
+      name: "showValues",
+      type: "boolean",
+      required: false,
+      default: true,
+      description: "Show each tier's `value` next to its label when present."
+    },
+    {
+      name: "onTierClick",
+      type: "function",
+      required: false,
+      description: "Called with the clicked PyramidTier."
+    },
+    {
+      name: "className",
+      type: "string",
+      required: false,
+      description: "Additional CSS classes on the SVG element."
+    }
+  ],
+  variants: [],
+  slots: [],
+  dependencies: {
+    npm: ["clsx", "tailwind-merge"],
+    internal: ["lib/utils"],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: ["primary", "primary-foreground", "background"],
+  examples: [
+    {
+      title: "Maslow's hierarchy",
+      description: "Classic widening pyramid with 5 tiers.",
+      code: '<Pyramid tiers={[\n  { id: "a", label: "Self-actualization" },\n  { id: "e", label: "Esteem" },\n  { id: "l", label: "Love & belonging" },\n  { id: "s", label: "Safety" },\n  { id: "p", label: "Physiological" },\n]} />',
+      composition: ["pyramid", "rank", "hierarchy"]
+    },
+    {
+      title: "Inverted pyramid (narrowing) for ranked output",
+      description: 'Use "narrowing" when the most important tier sits at the top.',
+      code: '<Pyramid shape="narrowing" tiers={[\n  { id: "north-star", label: "North star" },\n  { id: "okrs", label: "OKRs" },\n  { id: "projects", label: "Projects" },\n  { id: "tasks", label: "Tasks" },\n]} />',
+      composition: ["pyramid", "narrowing"]
+    }
+  ],
+  ai: {
+    whenToUse: "Visualize a ranked categorical hierarchy where tier order is meaningful but each tier is a distinct level (not a subset of the previous). Maslow-style needs hierarchy, organizational tiers, content hierarchy (north star \u2192 tasks).",
+    whenNotToUse: "Don't use for conversion drop-off where each stage is a strict subset of the previous (use Funnel \u2014 it shows the conversion ratio between stages). Don't use for value-scaled hierarchies (use TreeMap or Sunburst). Don't use for >7 tiers \u2014 labels become unreadable.",
+    commonMistakes: [
+      "Confusing Pyramid with Funnel \u2014 Funnel encodes FLOW (value moves between stages); Pyramid encodes RANK (each tier is a distinct level)",
+      "Tier order matters \u2014 the first array element is the apex. Reversing the array flips the meaning",
+      "Passing values that don't actually rank \u2014 Pyramid doesn't sort; it trusts your order"
+    ],
+    relatedComponents: ["funnel", "sankey", "tree-map", "sunburst"],
+    accessibilityNotes: 'The SVG carries role="img" with a <title> and <desc> summarizing tier count and shape. For agent outputs, also expose a parallel ordered list (<ol>) of labels so screen-reader users get the rank order without relying on visual position.',
+    tokenBudget: 260
+  },
+  tags: ["artifact", "diagram", "pyramid", "rank", "hierarchy"]
+};
+
+// src/artifacts/flowchart/flowchart.schema.ts
+var flowchartSchema = {
+  name: "flowchart",
+  displayName: "Flowchart",
+  description: "Typed React flowchart. Pass nodes (with optional shape) and directional edges; the component runs a topological-rank auto-layout and renders top-to-bottom or left-to-right. Pure SVG; no heavy peer dep.",
+  category: "artifact",
+  subcategory: "flow",
+  props: [
+    {
+      name: "nodes",
+      type: "object",
+      required: true,
+      description: 'Array of { id, label, shape?, rank? }. shape \u2208 "rect" (default) | "round" | "diamond".'
+    },
+    {
+      name: "edges",
+      type: "object",
+      required: true,
+      description: "Array of { source, target, label? }. The graph MUST be a DAG (no cycles)."
+    },
+    {
+      name: "direction",
+      type: "enum",
+      required: false,
+      default: "vertical",
+      description: "Layout direction \u2014 vertical (top-to-bottom) or horizontal (left-to-right).",
+      enumValues: ["vertical", "horizontal"]
+    },
+    {
+      name: "width",
+      type: "number",
+      required: false,
+      default: 720,
+      description: "SVG pixel width."
+    },
+    {
+      name: "height",
+      type: "number",
+      required: false,
+      default: 480,
+      description: "SVG pixel height."
+    },
+    {
+      name: "nodeWidth",
+      type: "number",
+      required: false,
+      default: 140,
+      description: "Pixel width of each node."
+    },
+    {
+      name: "nodeHeight",
+      type: "number",
+      required: false,
+      default: 48,
+      description: "Pixel height of each node."
+    },
+    {
+      name: "onNodeClick",
+      type: "function",
+      required: false,
+      description: "Called with the clicked FlowchartNode."
+    },
+    {
+      name: "className",
+      type: "string",
+      required: false,
+      description: "Additional CSS classes on the SVG element."
+    }
+  ],
+  variants: [],
+  slots: [],
+  dependencies: {
+    npm: ["clsx", "tailwind-merge"],
+    internal: ["lib/utils"],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: ["card", "border", "foreground", "muted-foreground", "background"],
+  examples: [
+    {
+      title: "Authorization decision flow",
+      description: "Diamond decision node + two outcomes.",
+      code: '<Flowchart\n  nodes={[\n    { id: "start", label: "Start", shape: "round" },\n    { id: "check", label: "Authorized?", shape: "diamond" },\n    { id: "ok", label: "Continue" },\n    { id: "denied", label: "Reject", shape: "round" },\n  ]}\n  edges={[\n    { source: "start", target: "check" },\n    { source: "check", target: "ok", label: "yes" },\n    { source: "check", target: "denied", label: "no" },\n  ]}\n/>',
+      composition: ["flowchart", "decision", "branching"]
+    },
+    {
+      title: "Horizontal pipeline with click handler",
+      description: "Left-to-right ETL stages.",
+      code: '<Flowchart\n  direction="horizontal"\n  nodes={stages}\n  edges={transitions}\n  onNodeClick={(n) => router.push(`/stages/${n.id}`)}\n/>',
+      composition: ["flowchart", "horizontal", "pipeline"]
+    }
+  ],
+  ai: {
+    whenToUse: "Render structured process / decision / pipeline diagrams from typed application data \u2014 onboarding flows, decision trees, ETL pipelines, agent step-graphs. Use when consumers want an SVG without the bundle cost of `<Diagram>` (Mermaid) or the free-form interaction of `<Canvas>` (ReactFlow).",
+    whenNotToUse: "Don't use for cyclic graphs (use Canvas \u2014 Flowchart's topological layout assumes a DAG). Don't use when consumers want to drag nodes around (use Canvas). Don't use when the diagram source is a Mermaid string from an LLM (use Diagram).",
+    commonMistakes: [
+      "Cycles in the edge graph \u2014 `computeRanks` short-circuits cycles to rank 0, which produces a degenerate layout. Validate the DAG upstream",
+      "An edge whose source or target id is missing from `nodes` \u2014 the edge is silently skipped. Validate ids upstream",
+      "Too many nodes at the same rank \u2014 the cross-axis spacing collapses. Either provide explicit `rank` overrides to balance the layout, or grow the SVG width",
+      "Mutating nodes/edges in place between renders \u2014 the layout pass treats inputs as immutable and re-runs on identity change"
+    ],
+    relatedComponents: ["sankey", "funnel", "diagram", "canvas", "mind-map"],
+    accessibilityNotes: 'The SVG carries role="img" with a <title> and <desc> summarizing node and edge counts. For agent outputs, also expose a parallel ordered list (or tree) of nodes-by-rank so screen-reader users get the flow without relying on visual position.',
+    tokenBudget: 380
+  },
+  tags: ["artifact", "diagram", "flowchart", "flow", "dag", "process"]
+};
+
+// src/artifacts/venn/venn.schema.ts
+var vennSchema = {
+  name: "venn",
+  displayName: "Venn",
+  description: "Set-overlap diagram for 2 or 3 sets. Pure SVG; no heavy peer dep. Shows categorical overlap (which sets intersect) \u2014 NOT exact intersection cardinality (use an Euler-diagram solver for that).",
+  category: "artifact",
+  subcategory: "relational",
+  props: [
+    {
+      name: "sets",
+      type: "object",
+      required: true,
+      description: "Array of { id, label, value? }. Must have 2 or 3 entries; other counts render a friendly fallback."
+    },
+    {
+      name: "size",
+      type: "number",
+      required: false,
+      default: 360,
+      description: "Pixel size of the rendered SVG (it's square)."
+    },
+    {
+      name: "onSetClick",
+      type: "function",
+      required: false,
+      description: "Called with the clicked VennSet."
+    },
+    {
+      name: "className",
+      type: "string",
+      required: false,
+      description: "Additional CSS classes on the SVG element."
+    }
+  ],
+  variants: [],
+  slots: [],
+  dependencies: {
+    npm: ["clsx", "tailwind-merge"],
+    internal: ["lib/utils"],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: ["primary", "accent", "secondary", "foreground", "muted-foreground", "background"],
+  examples: [
+    {
+      title: "Three-set Venn",
+      description: "Linux / Mac / Windows overlap.",
+      code: '<Venn sets={[\n  { id: "linux", label: "Linux" },\n  { id: "mac", label: "Mac" },\n  { id: "windows", label: "Windows" },\n]} />',
+      composition: ["venn", "set-overlap"]
+    },
+    {
+      title: "Two-set Venn with values",
+      description: "Show set sizes alongside labels.",
+      code: '<Venn sets={[\n  { id: "paid", label: "Paid", value: 1200 },\n  { id: "active", label: "Active", value: 480 },\n]} />',
+      composition: ["venn", "with-values"]
+    }
+  ],
+  ai: {
+    whenToUse: "Show that two or three categorical sets overlap \u2014 feature support matrices (Linux \u2229 Mac), cohort intersections (paid \u2229 active), tag overlap. Use when the SHAPE of the overlap is the message.",
+    whenNotToUse: "Don't use to communicate exact intersection sizes \u2014 circles are not area-scaled (use an Euler-diagram tool with a layout solver). Don't use for >3 sets \u2014 it stops being a Venn. Don't use for hierarchical / weighted / sequential relationships (use TreeMap, Sankey, Flowchart).",
+    commonMistakes: [
+      "Implying intersection cardinality from circle area \u2014 Venn circles are fixed-size visual references. The component does NOT solve for area-correct overlap regions; the schema documents this clearly",
+      "Passing 4+ sets \u2014 strict Venn diagrams with 4+ sets aren't visually tractable. The component renders a friendly fallback in that case",
+      "Mutating the sets array in place between renders \u2014 the layout pass is memoized on identity"
+    ],
+    relatedComponents: ["chord", "matrix", "arc", "tree-map"],
+    accessibilityNotes: 'The SVG carries role="img" with a <title> and <desc> listing the participating set labels. Interactive sets carry role="button", tabIndex, and Enter/Space activation. For agent outputs, also expose a parallel list of sets so screen-reader users get the labels without relying on the visual.',
+    tokenBudget: 280
+  },
+  tags: ["artifact", "diagram", "venn", "set-overlap", "relational"]
+};
+
+// src/artifacts/chord/chord.schema.ts
+var chordSchema = {
+  name: "chord",
+  displayName: "Chord",
+  description: 'Chord diagram. Nodes sit on a ring; ribbons inside encode weighted bidirectional relationships. Use for trade flows, migration, citation networks \u2014 "A relates to B with weight w" at scale.',
+  category: "artifact",
+  subcategory: "relational",
+  props: [
+    {
+      name: "nodes",
+      type: "object",
+      required: true,
+      description: "Array of { id, label }. Order matches matrix rows/columns."
+    },
+    {
+      name: "matrix",
+      type: "object",
+      required: true,
+      description: "Square N\xD7N matrix of weights. matrix[i][j] = flow from node i to node j."
+    },
+    {
+      name: "size",
+      type: "number",
+      required: false,
+      default: 480,
+      description: "Pixel size of the rendered SVG (it's square)."
+    },
+    {
+      name: "padAngle",
+      type: "number",
+      required: false,
+      default: 0.04,
+      description: "Padding (in radians) between adjacent ring segments."
+    },
+    {
+      name: "onChordHover",
+      type: "function",
+      required: false,
+      description: "Called with the hovered ribbon's { source, target, value } (or null when hover ends)."
+    },
+    {
+      name: "onNodeClick",
+      type: "function",
+      required: false,
+      description: "Called with the clicked ChordNode."
+    },
+    {
+      name: "className",
+      type: "string",
+      required: false,
+      description: "Additional CSS classes on the SVG element."
+    }
+  ],
+  variants: [],
+  slots: [],
+  dependencies: {
+    npm: ["clsx", "tailwind-merge"],
+    internal: ["lib/utils"],
+    peer: ["react", "react-dom"],
+    heavyPeer: [
+      {
+        name: "d3-chord",
+        version: "^3.0.1",
+        bundleKbGzip: 3,
+        reason: "Computes the chord layout (group ranges + chord pairs from the input matrix)"
+      },
+      {
+        name: "d3-shape",
+        version: "^3.2.0",
+        bundleKbGzip: 6,
+        reason: "Generates the SVG arc and ribbon paths (already a peer of Sunburst)"
+      }
+    ]
+  },
+  tokensUsed: ["primary", "accent", "secondary", "muted", "background", "foreground"],
+  examples: [
+    {
+      title: "Trade flow between four regions",
+      description: "Bidirectional weighted relationships.",
+      code: '<Chord\n  nodes={[\n    { id: "americas", label: "Americas" },\n    { id: "emea", label: "EMEA" },\n    { id: "apac", label: "APAC" },\n    { id: "africa", label: "Africa" },\n  ]}\n  matrix={[\n    [0, 12, 8, 1],\n    [10, 0, 5, 2],\n    [7, 4, 0, 3],\n    [1, 1, 2, 0],\n  ]}\n/>',
+      composition: ["chord", "trade-flow", "weighted"]
+    },
+    {
+      title: "Hover for ribbon details",
+      description: "Wire `onChordHover` to populate a tooltip.",
+      code: "<Chord nodes={people} matrix={interactions} onChordHover={(c) => setActive(c)} />",
+      composition: ["chord", "interactive"]
+    }
+  ],
+  ai: {
+    whenToUse: "Visualize bidirectional weighted relationships among a small set of entities (typically 4\u201312). Trade flows, migration corridors, citation/hyperlink networks, character interactions in narratives.",
+    whenNotToUse: "Don't use for hierarchical relationships (use TreeMap, Sunburst, OrgChart). Don't use for unidirectional flows where direction matters (use Sankey). Don't use for >~15 nodes \u2014 ribbons stack and become unreadable. Don't use for sparse matrices \u2014 most ribbons collapse to invisible.",
+    commonMistakes: [
+      "Non-square matrix \u2014 d3-chord requires N\xD7N where N matches `nodes.length`. Validate upstream",
+      "Asymmetric weights expected to render symmetrically \u2014 the component honors per-direction weights as given (matrix[i][j] vs matrix[j][i])",
+      "Mutating `nodes` / `matrix` between renders \u2014 the layout pass is memoized on identity. Memoize the matrix",
+      "NaN entries in the matrix \u2014 the inline `descending` comparator treats NaN as equal (vs d3.descending which returns NaN). Sort positions for NaN entries are unstable; sanitize upstream",
+      "Expecting `onChordHover.value` \u2014 the callback now exposes `{ sourceValue, targetValue }` so consumers see both directions of an asymmetric flow at once"
+    ],
+    relatedComponents: ["sankey", "matrix", "arc", "venn"],
+    accessibilityNotes: 'The SVG carries role="img" with a <title> and <desc> summarizing node and ribbon counts. Interactive ribbons and node arcs declare role="button", tabIndex, and Enter/Space activation. For agent outputs, also expose a parallel adjacency table so screen-reader users get the matrix without relying on the visual.',
+    tokenBudget: 360
+  },
+  tags: ["artifact", "diagram", "chord", "relational", "weighted", "circular"]
+};
+
+// src/artifacts/arc/arc.schema.ts
+var arcSchema = {
+  name: "arc",
+  displayName: "Arc",
+  description: "Arc diagram. Nodes lie on a horizontal baseline; relationships are drawn as semicircle arcs above. Pure SVG; no heavy peer dep. Use when node ORDER matters (sequence, time, story position).",
+  category: "artifact",
+  subcategory: "relational",
+  props: [
+    {
+      name: "nodes",
+      type: "object",
+      required: true,
+      description: "Array of { id, label, value? }. Display order along the baseline matches array order."
+    },
+    {
+      name: "edges",
+      type: "object",
+      required: true,
+      description: "Array of { source, target, value? }. Edges with missing source/target are skipped."
+    },
+    {
+      name: "width",
+      type: "number",
+      required: false,
+      default: 720,
+      description: "SVG pixel width."
+    },
+    {
+      name: "height",
+      type: "number",
+      required: false,
+      default: 360,
+      description: "SVG pixel height."
+    },
+    {
+      name: "nodeRadius",
+      type: "number",
+      required: false,
+      default: 5,
+      description: "Pixel radius of each node circle."
+    },
+    {
+      name: "onEdgeHover",
+      type: "function",
+      required: false,
+      description: "Called with the hovered ArcEdge (or null when hover ends)."
+    },
+    {
+      name: "onNodeClick",
+      type: "function",
+      required: false,
+      description: "Called with the clicked ArcNode."
+    },
+    {
+      name: "className",
+      type: "string",
+      required: false,
+      description: "Additional CSS classes on the SVG element."
+    }
+  ],
+  variants: [],
+  slots: [],
+  dependencies: {
+    npm: ["clsx", "tailwind-merge"],
+    internal: ["lib/utils"],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: ["primary", "background", "foreground"],
+  examples: [
+    {
+      title: "Character co-occurrence",
+      description: "Nodes in narrative order, arcs connect characters in the same chapter.",
+      code: "<Arc\n  nodes={characters}\n  edges={cooccurrences}\n  onEdgeHover={(e) => setActive(e)}\n/>",
+      composition: ["arc", "narrative", "cooccurrence"]
+    },
+    {
+      title: "Train route transfer connections",
+      description: "Stations on a baseline; arcs show transfer connections.",
+      code: "<Arc\n  nodes={stations}\n  edges={transfers}\n/>",
+      composition: ["arc", "transit", "sequence"]
+    }
+  ],
+  ai: {
+    whenToUse: "Visualize relationships among entities WHERE THE ORDER OF ENTITIES IS MEANINGFUL \u2014 narrative co-occurrence (chapters), transit transfer points (route order), genome interactions (chromosomal position), citation networks (publication time). Arcs encode pair relationships without breaking the linear node order.",
+    whenNotToUse: "Don't use when node order is arbitrary (use Chord \u2014 it places nodes on a ring with no implied order). Don't use for hierarchical relationships (use TreeMap, Sunburst, OrgChart). Don't use for >50 nodes \u2014 arcs overlap heavily; consider Matrix.",
+    commonMistakes: [
+      "Confusing Arc with Chord \u2014 Chord = ring (no order); Arc = baseline (order matters)",
+      "Edge source/target id missing from `nodes` \u2014 silently skipped. Validate ids upstream",
+      "Mutating nodes / edges between renders \u2014 the layout pass is memoized on identity"
+    ],
+    relatedComponents: ["chord", "matrix", "venn", "sankey"],
+    accessibilityNotes: 'The SVG carries role="img" with a <title> and <desc> summarizing node and edge counts. Interactive nodes/edges declare role="button", tabIndex, and Enter/Space activation. For agent outputs, also expose a parallel ordered list of nodes plus an adjacency table.',
+    tokenBudget: 320
+  },
+  tags: ["artifact", "diagram", "arc", "relational", "sequence", "ordered"]
+};
+
+// src/artifacts/matrix/matrix.schema.ts
+var matrixSchema = {
+  name: "matrix",
+  displayName: "Matrix",
+  description: "Adjacency-matrix diagram. Square grid where cell color intensity encodes the relationship from row to column. Pure SVG; no heavy peer dep. Best for dense graphs that turn into hairballs in node-link form.",
+  category: "artifact",
+  subcategory: "relational",
+  props: [
+    {
+      name: "nodes",
+      type: "object",
+      required: true,
+      description: "Array of { id, label }. Used as both rows AND columns. Order matches `matrix` rows/columns."
+    },
+    {
+      name: "matrix",
+      type: "object",
+      required: true,
+      description: "Square N\xD7N matrix. matrix[i][j] = relationship from node i to node j. Renamed from `values` to avoid colliding with the SVG `values` animation attribute."
+    },
+    {
+      name: "size",
+      type: "number",
+      required: false,
+      default: 480,
+      description: "Pixel size of the rendered SVG (it's square)."
+    },
+    {
+      name: "labelMargin",
+      type: "number",
+      required: false,
+      default: 80,
+      description: "Pixel reserved for row/column labels along the top and left edges."
+    },
+    {
+      name: "showValues",
+      type: "boolean",
+      required: false,
+      default: true,
+      description: "Show numeric values inside cells when the cell is large enough (~28px+)."
+    },
+    {
+      name: "onCellHover",
+      type: "function",
+      required: false,
+      description: "Called with the hovered cell's { row, col, value } (or null when hover ends)."
+    },
+    {
+      name: "onCellClick",
+      type: "function",
+      required: false,
+      description: "Called with the clicked cell's { row, col, value }."
+    },
+    {
+      name: "className",
+      type: "string",
+      required: false,
+      description: "Additional CSS classes on the SVG element."
+    }
+  ],
+  variants: [],
+  slots: [],
+  dependencies: {
+    npm: ["clsx", "tailwind-merge"],
+    internal: ["lib/utils"],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: ["primary", "background", "foreground"],
+  examples: [
+    {
+      title: "Trade flow matrix",
+      description: "Cell intensity reflects flow from row region to column region.",
+      code: "<Matrix\n  nodes={regions}\n  matrix={tradeFlow}\n  onCellHover={(c) => setActive(c)}\n/>",
+      composition: ["matrix", "trade-flow", "heatmap"]
+    },
+    {
+      title: "Confusion matrix for a classifier",
+      description: "Predicted vs actual labels.",
+      code: "<Matrix\n  nodes={classes}\n  matrix={confusion}\n  showValues={true}\n/>",
+      composition: ["matrix", "confusion", "ml"]
+    }
+  ],
+  ai: {
+    whenToUse: "Visualize a dense relationship between many pairs of entities \u2014 adjacency matrices, confusion matrices, correlation matrices, trade-flow matrices, citation-count matrices. Scales gracefully to ~100 nodes where node-link diagrams degenerate. Use when SCALE matters more than seeing individual edges.",
+    whenNotToUse: "Don't use for sparse relationships (most cells empty \u2014 Sankey or Arc surfaces the actual edges better). Don't use when the user needs to follow paths from node to node (use Canvas, Flowchart). Don't use for hierarchical data (use TreeMap, Sunburst).",
+    commonMistakes: [
+      "Non-square `matrix` \u2014 the component reads matrix[i][j], so missing rows or short rows render as zero. Validate dimensions upstream",
+      "Mismatched length: `nodes.length` \u2260 `matrix.length` \u2014 extra nodes get blank rows; extra rows are ignored. Validate upstream",
+      "Mutating `nodes` / `matrix` between renders \u2014 the layout pass is memoized on identity",
+      "Asymmetric values expected to render symmetrically \u2014 the component honors per-direction values exactly as given",
+      "`labelMargin` smaller than the longest node label's pixel width \u2014 labels overflow the SVG. Set `labelMargin` \u2265 ~0.75\xD7 longestLabelPx, or shorten labels upstream"
+    ],
+    relatedComponents: ["chord", "arc", "venn", "sankey"],
+    accessibilityNotes: 'The SVG carries role="img" with a <title> and <desc> summarizing dimensions. Interactive cells declare role="button", tabIndex, and Enter/Space activation; hover/focus fire callback symmetrically. For agent outputs, also expose a parallel <table> so screen-reader users get the values without relying on color intensity.',
+    tokenBudget: 360
+  },
+  tags: ["artifact", "diagram", "matrix", "adjacency", "relational", "heatmap"]
+};
+
+// src/artifacts/time-axis/time-axis.schema.ts
+var timeAxisSchema = {
+  name: "time-axis",
+  displayName: "TimeAxis",
+  description: "Events plotted along a horizontal time axis. Pure SVG; no heavy peer dep. Distinct from the existing event-list `<Timeline>` \u2014 TimeAxis encodes elapsed time as horizontal distance, so the *gap between events* is the message.",
+  category: "artifact",
+  subcategory: "time",
+  props: [
+    {
+      name: "events",
+      type: "object",
+      required: true,
+      description: "Array of { id, label, date, category? }. `date` accepts Date / ISO string / epoch ms."
+    },
+    {
+      name: "start",
+      type: "object",
+      required: false,
+      description: "Optional explicit axis start. Auto-derived from `events` if omitted."
+    },
+    {
+      name: "end",
+      type: "object",
+      required: false,
+      description: "Optional explicit axis end. Auto-derived from `events` if omitted."
+    },
+    {
+      name: "width",
+      type: "number",
+      required: false,
+      default: 720,
+      description: "SVG pixel width."
+    },
+    {
+      name: "height",
+      type: "number",
+      required: false,
+      default: 200,
+      description: "SVG pixel height."
+    },
+    {
+      name: "tickCount",
+      type: "number",
+      required: false,
+      default: 6,
+      description: "Number of axis ticks to show."
+    },
+    {
+      name: "onEventClick",
+      type: "function",
+      required: false,
+      description: "Called with the clicked TimeAxisEvent."
+    },
+    {
+      name: "className",
+      type: "string",
+      required: false,
+      description: "Additional CSS classes on the SVG element."
+    }
+  ],
+  variants: [],
+  slots: [],
+  dependencies: {
+    npm: ["clsx", "tailwind-merge"],
+    internal: ["lib/utils"],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: ["primary", "background", "foreground", "muted-foreground"],
+  examples: [
+    {
+      title: "Release timeline",
+      description: "Major version releases plotted across a year.",
+      code: '<TimeAxis events={[\n  { id: "v1", label: "v1.0", date: "2025-01-15" },\n  { id: "v2", label: "v2.0", date: "2025-04-20" },\n  { id: "v3", label: "v3.0", date: "2025-09-10" },\n]} />',
+      composition: ["time-axis", "release"]
+    },
+    {
+      title: "Incident frequency with explicit range",
+      description: "Pin the axis to the quarter to compare incident clustering.",
+      code: '<TimeAxis\n  start="2025-07-01"\n  end="2025-09-30"\n  events={incidents}\n  onEventClick={(e) => router.push(`/incidents/${e.id}`)}\n/>',
+      composition: ["time-axis", "incidents"]
+    }
+  ],
+  ai: {
+    whenToUse: "Plot events along a horizontal time axis where the *gap between events* matters \u2014 release cadence, incident frequency, sparse-then-dense activity, project milestones across a year. Auto-stacks overlapping events into rows.",
+    whenNotToUse: "Don't use when only event ORDER matters and absolute dates are secondary (use the existing event-list `<Timeline>` in `components/`). Don't use for tasks with duration (use Gantt). Don't use for actor-message interactions (use Sequence).",
+    commonMistakes: [
+      'Passing dates as strings in non-ISO formats \u2014 `new Date("01/02/2025")` is locale-dependent. Pass ISO strings (`"2025-01-02"`), Date objects, or epoch ms',
+      "Forgetting to set `start`/`end` when comparing two TimeAxis renders side-by-side \u2014 auto-range scales each axis to its own events, which makes magnitudes incomparable. Pin the range explicitly",
+      "Mutating `events` between renders \u2014 the layout pass is memoized on identity",
+      "Confusing TimeAxis with the existing `<Timeline>` in `components/` \u2014 they coexist intentionally; pick by whether elapsed-time spacing matters"
+    ],
+    relatedComponents: ["gantt", "sequence", "timeline"],
+    accessibilityNotes: 'The SVG carries role="img" with a <title> and <desc> summarizing event count and axis range. Interactive event markers declare role="button", tabIndex, and Enter/Space activation. For agent outputs, also expose a parallel chronologically-ordered list of label/date pairs.',
+    tokenBudget: 320
+  },
+  tags: ["artifact", "diagram", "time-axis", "time", "events", "chronological"]
+};
+
+// src/artifacts/gantt/gantt.schema.ts
+var ganttSchema = {
+  name: "gantt",
+  displayName: "Gantt",
+  description: "Gantt chart \u2014 tasks as horizontal bars across a time axis with optional dependency arrows and progress fills. Pure SVG; no heavy peer dep.",
+  category: "artifact",
+  subcategory: "time",
+  props: [
+    {
+      name: "tasks",
+      type: "object",
+      required: true,
+      description: "Array of { id, label, start, end, progress?, dependencies? }. `start`/`end` accept Date / ISO string / epoch ms."
+    },
+    {
+      name: "width",
+      type: "number",
+      required: false,
+      default: 800,
+      description: "SVG pixel width."
+    },
+    {
+      name: "rowHeight",
+      type: "number",
+      required: false,
+      default: 32,
+      description: "Pixel height of each task row."
+    },
+    {
+      name: "labelMargin",
+      type: "number",
+      required: false,
+      default: 140,
+      description: "Pixel reserved on the left for task labels."
+    },
+    {
+      name: "tickCount",
+      type: "number",
+      required: false,
+      default: 6,
+      description: "Number of axis ticks to show across the top."
+    },
+    {
+      name: "onTaskClick",
+      type: "function",
+      required: false,
+      description: "Called with the clicked GanttTask."
+    },
+    {
+      name: "className",
+      type: "string",
+      required: false,
+      description: "Additional CSS classes on the SVG element."
+    }
+  ],
+  variants: [],
+  slots: [],
+  dependencies: {
+    npm: ["clsx", "tailwind-merge"],
+    internal: ["lib/utils"],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: ["primary", "foreground", "muted-foreground", "background"],
+  examples: [
+    {
+      title: "Project schedule with dependencies",
+      description: "Sequential tasks with dependency arrows and a progress fill.",
+      code: '<Gantt tasks={[\n  { id: "design", label: "Design", start: "2025-01-01", end: "2025-01-15", progress: 1 },\n  { id: "build", label: "Build", start: "2025-01-10", end: "2025-02-20", progress: 0.6, dependencies: ["design"] },\n  { id: "ship", label: "Ship", start: "2025-02-15", end: "2025-02-28", dependencies: ["build"] },\n]} />',
+      composition: ["gantt", "schedule", "dependencies"]
+    },
+    {
+      title: "Sprint board across two weeks",
+      description: "Click a bar to open the task detail.",
+      code: "<Gantt\n  tasks={sprint}\n  onTaskClick={(t) => router.push(`/tasks/${t.id}`)}\n/>",
+      composition: ["gantt", "sprint"]
+    }
+  ],
+  ai: {
+    whenToUse: "Visualize project schedules where each task has a START and END date, plus optional dependencies and progress. Sprint boards, release plans, ETL job schedules, content publishing calendars.",
+    whenNotToUse: "Don't use for point events without duration (use TimeAxis). Don't use for cyclic / recurring tasks (Gantt assumes a DAG of dependencies). Don't use for actor-message interactions (use Sequence). Don't use when the task list isn't ordered top-to-bottom by intended display order \u2014 Gantt trusts the array order.",
+    commonMistakes: [
+      "`end` before `start` \u2014 produces zero-or-negative width bars. Validate ranges upstream",
+      "Dependency cycles \u2014 `dependencies: ['x']` where `x` transitively depends on the current task. The component still renders bars, but the arrow paths cross awkwardly. Validate the dependency DAG upstream",
+      "Missing dependency target \u2014 `dependencies: ['ghost']` where `ghost` isn't in `tasks`. The arrow is silently skipped",
+      'Passing dates as locale-dependent strings (`"01/02/2025"`) \u2014 pass ISO (`"2025-01-02"`), Date, or epoch ms',
+      "Mutating tasks between renders \u2014 the layout pass is memoized on identity"
+    ],
+    relatedComponents: ["time-axis", "sequence", "timeline", "flowchart"],
+    accessibilityNotes: 'The SVG carries role="img" with a <title> and <desc> summarizing task count and date range. Interactive task bars declare role="button", tabIndex, and Enter/Space activation. The aria-label includes label, date range, and progress percent. For agent outputs, also expose a parallel ordered list of tasks with their dates.',
+    tokenBudget: 360
+  },
+  tags: ["artifact", "diagram", "gantt", "time", "schedule", "tasks"]
+};
+
+// src/artifacts/sequence/sequence.schema.ts
+var sequenceSchema = {
+  name: "sequence",
+  displayName: "Sequence",
+  description: "UML-style sequence diagram. Actors as columns with vertical lifelines; messages as horizontal arrows in declaration order. Pure SVG; no heavy peer dep.",
+  category: "artifact",
+  subcategory: "time",
+  props: [
+    {
+      name: "actors",
+      type: "object",
+      required: true,
+      description: "Array of { id, label }. Display order matches array order (left-to-right columns)."
+    },
+    {
+      name: "messages",
+      type: "object",
+      required: true,
+      description: "Array of { from, to, label?, type? }. Chronological order matches array order (top-to-bottom). Messages whose `from` or `to` actor id is missing are silently skipped."
+    },
+    {
+      name: "width",
+      type: "number",
+      required: false,
+      default: 720,
+      description: "SVG pixel width."
+    },
+    {
+      name: "headerHeight",
+      type: "number",
+      required: false,
+      default: 40,
+      description: "Pixel height of each actor header."
+    },
+    {
+      name: "messageGap",
+      type: "number",
+      required: false,
+      default: 36,
+      description: "Pixel vertical gap between consecutive messages."
+    },
+    {
+      name: "onActorClick",
+      type: "function",
+      required: false,
+      description: "Called with the clicked SequenceActor."
+    },
+    {
+      name: "onMessageClick",
+      type: "function",
+      required: false,
+      description: "Called with the clicked SequenceMessage."
+    },
+    {
+      name: "className",
+      type: "string",
+      required: false,
+      description: "Additional CSS classes on the SVG element."
+    }
+  ],
+  variants: [],
+  slots: [],
+  dependencies: {
+    npm: ["clsx", "tailwind-merge"],
+    internal: ["lib/utils"],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: ["card", "border", "foreground", "muted-foreground", "background"],
+  examples: [
+    {
+      title: "Signup flow",
+      description: "User \u2192 API \u2192 DB with return arrows.",
+      code: '<Sequence\n  actors={[\n    { id: "user", label: "User" },\n    { id: "api", label: "API" },\n    { id: "db", label: "DB" },\n  ]}\n  messages={[\n    { from: "user", to: "api", label: "POST /signup" },\n    { from: "api", to: "db", label: "INSERT user" },\n    { from: "db", to: "api", label: "ok", type: "return" },\n    { from: "api", to: "user", label: "201 Created", type: "return" },\n  ]}\n/>',
+      composition: ["sequence", "api-flow"]
+    },
+    {
+      title: "Self-call (loopback) message",
+      description: "An actor calling itself renders as a loopback arrow.",
+      code: '<Sequence\n  actors={[{ id: "worker", label: "Worker" }]}\n  messages={[{ from: "worker", to: "worker", label: "retry" }]}\n/>',
+      composition: ["sequence", "self-call"]
+    }
+  ],
+  ai: {
+    whenToUse: "Visualize WHO talks to WHO and IN WHAT ORDER \u2014 API request flows, distributed-system protocols, agent tool-call sequences, OAuth dance, message-queue choreography. Use when the order and direction of messages between actors is the message.",
+    whenNotToUse: "Don't use for branching process diagrams (use Flowchart). Don't use for events along a real time axis (use TimeAxis). Don't use for tasks with duration (use Gantt). Don't use for >~8 actors \u2014 columns become too narrow to read messages on.",
+    commonMistakes: [
+      "`from` or `to` referencing an id missing from `actors` \u2014 the message is silently skipped. Validate ids upstream",
+      "Mutating actors / messages between renders \u2014 the layout pass is memoized on identity",
+      "Reordering `actors` to fix layout while keeping message ordering \u2014 that flips the visual flow direction. Order actors by their natural left-to-right reading order",
+      'Using `type: "return"` for forward-going messages \u2014 the dashed style implies a reply, so confused readers expect a prior outgoing message'
+    ],
+    relatedComponents: ["flowchart", "time-axis", "gantt", "canvas", "diagram"],
+    accessibilityNotes: 'The SVG carries role="img" with a <title> and <desc> summarizing actor and message counts. Interactive actor headers and message arrows declare role="button", tabIndex, and Enter/Space activation. The aria-label on each message includes its index, source/target labels, and content. For agent outputs, also expose a parallel ordered list of messages with their from/to/label triples.',
+    tokenBudget: 360
+  },
+  tags: ["artifact", "diagram", "sequence", "uml", "time", "messaging"]
+};
+
+// src/artifacts/flashcard/flashcard.schema.ts
+var flashcardSchema = {
+  name: "flashcard",
+  displayName: "Flashcard",
+  description: "Front/back card with a 3D flip animation on click. Pure CSS 3D transform; no animation peer. Headless on content \u2014 front and back accept any ReactNode. Pairs with Deck for session-level paging and SpacedRepetition for confidence rating.",
+  category: "artifact",
+  subcategory: "study",
+  props: [
+    {
+      name: "front",
+      type: "ReactNode",
+      required: true,
+      description: "Content of the front face."
+    },
+    {
+      name: "back",
+      type: "ReactNode",
+      required: true,
+      description: "Content of the back face."
+    },
+    {
+      name: "defaultFlipped",
+      type: "boolean",
+      required: false,
+      default: false,
+      description: "Uncontrolled initial flipped state."
+    },
+    {
+      name: "flipped",
+      type: "boolean",
+      required: false,
+      description: "Controlled flipped state. When set, internal state is ignored."
+    },
+    {
+      name: "onFlipChange",
+      type: "function",
+      required: false,
+      description: "Called with the new flipped value when the user toggles."
+    },
+    {
+      name: "width",
+      type: "number",
+      required: false,
+      default: 360,
+      description: "Pixel width."
+    },
+    {
+      name: "height",
+      type: "number",
+      required: false,
+      default: 240,
+      description: "Pixel height."
+    },
+    {
+      name: "flipDurationMs",
+      type: "number",
+      required: false,
+      default: 500,
+      description: "Flip animation duration in ms. Set to 0 to disable the animation entirely."
+    },
+    {
+      name: "className",
+      type: "string",
+      required: false,
+      description: "Additional CSS classes on the outer container."
+    }
+  ],
+  variants: [],
+  slots: [
+    {
+      name: "front",
+      description: "Front face of the card \u2014 typically the prompt / question / term.",
+      required: true
+    },
+    {
+      name: "back",
+      description: "Back face of the card \u2014 typically the answer / definition.",
+      required: true
+    }
+  ],
+  dependencies: {
+    npm: ["clsx", "tailwind-merge"],
+    internal: ["lib/utils"],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: ["card", "card-foreground", "border", "ring"],
+  examples: [
+    {
+      title: "Capital city flashcard",
+      description: "Classic question-answer card with default uncontrolled state.",
+      code: '<Flashcard front="What is the capital of France?" back="Paris" />',
+      composition: ["flashcard", "study", "qa"]
+    },
+    {
+      title: "Controlled flashcard inside a Deck",
+      description: "Parent owns the flipped state to coordinate with progress tracking.",
+      code: "<Flashcard\n  flipped={isFlipped}\n  onFlipChange={setFlipped}\n  front={term}\n  back={definition}\n/>",
+      composition: ["flashcard", "controlled"]
+    }
+  ],
+  ai: {
+    whenToUse: "Render a single self-test prompt where the user retrieves an answer from memory before checking. Vocabulary terms, formula reminders, anatomy labels, code snippets \u2014 anywhere the active-recall pattern (think first, then flip) fits.",
+    whenNotToUse: "Don't use for multiple-choice questions (use Quiz). Don't use for fill-in-the-blank (use Cloze). Don't use for image regions (use ImageOcclusion). Don't use as a generic content card with no flip semantics (use the existing `Card` in components/).",
+    commonMistakes: [
+      "Putting the answer on the front \u2014 defeats the active-recall pattern. Front should be the prompt only",
+      "Mixing controlled and uncontrolled use \u2014 pass either `flipped` (controlled) or rely on `defaultFlipped` + internal state, not both",
+      "Wrapping a Flashcard in another clickable parent \u2014 Enter / Space activations bubble; the parent's onClick fires too. Stop propagation in the wrapper or move the click handler",
+      "Sizing the card to 0\xD70 \u2014 the 3D transform requires non-zero dimensions to avoid the back face leaking through during the rotation"
+    ],
+    relatedComponents: ["cloze", "quiz", "image-occlusion", "deck", "spaced-repetition", "card"],
+    accessibilityNotes: `The card declares role="button", tabIndex=0, aria-pressed reflecting flipped state, and an aria-label that announces the current side. Enter and Space toggle the flip; Space's default page-scroll is preventDefaulted. Screen readers see both faces in DOM at all times \u2014 that's intentional so the back face is announced after the flip without a content swap.`,
+    tokenBudget: 280
+  },
+  tags: ["artifact", "study", "flashcard", "active-recall", "card"]
+};
+
+// src/artifacts/cloze/cloze.schema.ts
+var clozeSchema = {
+  name: "cloze",
+  displayName: "Cloze",
+  description: "Cloze-deletion text \u2014 sentences with redacted spans the learner reveals one at a time (or all at once). Pure HTML; no heavy peer.",
+  category: "artifact",
+  subcategory: "study",
+  props: [
+    {
+      name: "parts",
+      type: "object",
+      required: true,
+      description: "Mixed array of string fragments and { hidden, id? } cloze tokens. Each `hidden` value is the text the learner has to recall."
+    },
+    {
+      name: "revealMode",
+      type: "enum",
+      required: false,
+      default: "click",
+      description: '"click" \u2014 reveals one blank at a time (default). "all" \u2014 adds a "Reveal all" toggle that flips every blank in one shot.',
+      enumValues: ["click", "all"]
+    },
+    {
+      name: "onReveal",
+      type: "function",
+      required: false,
+      description: "Called with the cumulative array of revealed blank ids whenever a blank toggles."
+    },
+    {
+      name: "className",
+      type: "string",
+      required: false,
+      description: "Additional CSS classes on the outer container."
+    }
+  ],
+  variants: [],
+  slots: [],
+  dependencies: {
+    npm: ["clsx", "tailwind-merge"],
+    internal: ["lib/utils"],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: ["primary", "muted", "foreground", "background", "border", "ring"],
+  examples: [
+    {
+      title: "Single-blank biology fact",
+      description: "Classic cloze with one redacted term.",
+      code: '<Cloze parts={[\n  "The mitochondria is the ",\n  { hidden: "powerhouse" },\n  " of the cell.",\n]} />',
+      composition: ["cloze", "study", "fill-in"]
+    },
+    {
+      title: "Multi-blank with reveal-all",
+      description: 'Useful when consumers want a quick "show me everything" escape hatch.',
+      code: '<Cloze\n  revealMode="all"\n  parts={[\n    "The capital of ",\n    { hidden: "France" },\n    " is ",\n    { hidden: "Paris" },\n    ".",\n  ]}\n/>',
+      composition: ["cloze", "multi-blank"]
+    }
+  ],
+  ai: {
+    whenToUse: "Render a sentence-level fill-in-the-blank where the learner can target ANY missing piece independently \u2014 vocabulary in context, formula completion, code snippets with redacted operators. Especially strong when the surrounding context is the cue.",
+    whenNotToUse: "Don't use for question-answer pairs (use Flashcard). Don't use for multiple-choice (use Quiz). Don't use for image labels (use ImageOcclusion). Don't use when blanks should be free-typed and graded \u2014 Cloze is reveal-only.",
+    commonMistakes: [
+      "Putting too much text in a single hidden token \u2014 the redacted block becomes the entire sentence and there's no context left to cue recall. Keep hidden segments to 1\u20133 words",
+      "Forgetting that string fragments matter \u2014 `parts: [{hidden:'a'},{hidden:'b'}]` produces two adjacent blanks with no surrounding text. The cue context lives in the string fragments between blanks",
+      "Reusing the same explicit `id` across multiple blanks \u2014 they reveal together because revealed-state keys off id. Either omit `id` (auto-numbered with a non-collidable prefix) or give each blank a unique id",
+      "Mutating `parts` between renders \u2014 the layout pass is memoized on identity",
+      "Treating Cloze as anti-cheating \u2014 the hidden text always lives in the DOM (transparent + user-select:none) so screen readers can announce it after reveal. A determined sighted user can still inspect element. Cloze is a recall *aid*, not a *secret*"
+    ],
+    relatedComponents: ["flashcard", "quiz", "image-occlusion", "deck", "spaced-repetition"],
+    accessibilityNotes: `Each blank renders as a real <button> with type="button", aria-pressed reflecting reveal state, and an aria-label that names the blank's index and total. The hidden text always lives in the DOM (transparent when unrevealed) so screen readers announce the answer once aria-pressed flips. Enter and Space activate via the native button behavior.`,
+    tokenBudget: 280
+  },
+  tags: ["artifact", "study", "cloze", "fill-in-the-blank", "active-recall"]
+};
+
+// src/artifacts/image-occlusion/image-occlusion.schema.ts
+var imageOcclusionSchema = {
+  name: "image-occlusion",
+  displayName: "ImageOcclusion",
+  description: "Image with rectangular regions hidden behind opaque overlays. Click any region to reveal what's underneath. Pure HTML; no heavy peer. Coordinates are 0\u20131 fractions so the layout stays correct at any rendered size.",
+  category: "artifact",
+  subcategory: "study",
+  props: [
+    {
+      name: "src",
+      type: "string",
+      required: true,
+      description: "Image source URL."
+    },
+    {
+      name: "alt",
+      type: "string",
+      required: true,
+      description: "Alt text for the underlying image."
+    },
+    {
+      name: "regions",
+      type: "object",
+      required: true,
+      description: "Array of { id, x, y, width, height, label? }. All coords are 0\u20131 fractions of the rendered image."
+    },
+    {
+      name: "onRegionReveal",
+      type: "function",
+      required: false,
+      description: "Called with the region id when a region is revealed (NOT when hidden again)."
+    },
+    {
+      name: "className",
+      type: "string",
+      required: false,
+      description: "Additional CSS classes on the outer container."
+    }
+  ],
+  variants: [],
+  slots: [],
+  dependencies: {
+    npm: ["clsx", "tailwind-merge"],
+    internal: ["lib/utils"],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: ["primary", "ring"],
+  examples: [
+    {
+      title: "Anatomy diagram",
+      description: "Heart cross-section with named chambers occluded.",
+      code: '<ImageOcclusion\n  src="/anatomy/heart.png"\n  alt="Cross-section of a human heart"\n  regions={[\n    { id: "lv", x: 0.42, y: 0.55, width: 0.18, height: 0.22, label: "Left ventricle" },\n    { id: "ra", x: 0.58, y: 0.20, width: 0.16, height: 0.18, label: "Right atrium" },\n  ]}\n/>',
+      composition: ["image-occlusion", "anatomy"]
+    },
+    {
+      title: "Code snippet with redacted operators",
+      description: "Hide language operators and have the learner reveal them.",
+      code: '<ImageOcclusion\n  src="/code/snippet.png"\n  alt="JavaScript array map"\n  regions={[\n    { id: "op1", x: 0.30, y: 0.10, width: 0.05, height: 0.08 },\n  ]}\n  onRegionReveal={(id) => track(id)}\n/>',
+      composition: ["image-occlusion", "code"]
+    }
+  ],
+  ai: {
+    whenToUse: "Hide labels or sub-regions of a visual the learner needs to recall. Anatomy diagrams, geographic maps, code snippets, anatomical illustrations, mathematical figures \u2014 any image where the recall target is a region rather than the whole.",
+    whenNotToUse: "Don't use for text-only fill-in-the-blank (use Cloze). Don't use when the entire image is the answer (use Flashcard with the image on `back`). Don't use when regions overlap heavily \u2014 overlapping overlays interfere with click targets.",
+    commonMistakes: [
+      "Passing pixel coordinates instead of fractions \u2014 `x: 168` instead of `x: 0.42`. The component warns in dev when any region's coords escape [0, 1]",
+      "Region rectangles smaller than ~20px square \u2014 too tiny to hit on touch devices. Aim for \u226540 \xD7 40px at the rendered image size",
+      "Heavily overlapping regions \u2014 later array entries get higher z-index and catch the click; regions earlier in the array are visible but unclickable underneath. Order regions back-to-front (largest/outermost first, smallest/innermost last)",
+      "Mutating the regions array between renders \u2014 react re-runs reveal state, but the input identity matters for any downstream memoization. Memoize the regions array"
+    ],
+    relatedComponents: ["flashcard", "cloze", "quiz", "deck", "spaced-repetition"],
+    accessibilityNotes: `Each overlay is a real <button> with type="button", aria-pressed reflecting reveal state, and an aria-label that names the region's index, total, and label (when provided). The underlying <img> carries the user-supplied alt text. The decorative overlay container is aria-hidden so screen readers don't double-announce regions.`,
+    tokenBudget: 320
+  },
+  tags: ["artifact", "study", "image-occlusion", "active-recall", "visual"]
+};
+
+// src/artifacts/quiz/quiz.schema.ts
+var quizSchema = {
+  name: "quiz",
+  displayName: "Quiz",
+  description: 'Single-question multiple-choice quiz with submit + reveal. After submit, each option is tagged data-state="correct|incorrect|missed" so consumers can theme right / wrong / unselected-but-correct independently. Pure HTML; no heavy peer.',
+  category: "artifact",
+  subcategory: "study",
+  props: [
+    {
+      name: "question",
+      type: "ReactNode",
+      required: true,
+      description: "The question prompt \u2014 accepts any rich content."
+    },
+    {
+      name: "options",
+      type: "object",
+      required: true,
+      description: "Array of { id, label, correct?, explanation? }. `correct: true` flags the right answer(s); `explanation` renders below the option after submit."
+    },
+    {
+      name: "selectionMode",
+      type: "enum",
+      required: false,
+      default: "single",
+      description: '"single" \u2014 radio inputs (one pick); "multi" \u2014 checkboxes (zero or more picks).',
+      enumValues: ["single", "multi"]
+    },
+    {
+      name: "submitLabel",
+      type: "string",
+      required: false,
+      default: "Submit",
+      description: "Custom Submit button text."
+    },
+    {
+      name: "onAnswer",
+      type: "function",
+      required: false,
+      description: "Called with (selectedIds, allCorrect) on submit. `allCorrect` is true only when the picked set equals the correct set exactly (multi-select must include all correct AND nothing extra)."
+    },
+    {
+      name: "className",
+      type: "string",
+      required: false,
+      description: "Additional CSS classes on the outer container."
+    }
+  ],
+  variants: [],
+  slots: [],
+  dependencies: {
+    npm: ["clsx", "tailwind-merge"],
+    internal: ["lib/utils"],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: ["card", "card-foreground", "background", "border", "primary", "primary-foreground", "destructive", "muted", "muted-foreground", "ring"],
+  examples: [
+    {
+      title: "Single-answer geography",
+      description: "Standard one-correct multiple choice.",
+      code: '<Quiz\n  question="Which planet is closest to the sun?"\n  options={[\n    { id: "m", label: "Mercury", correct: true },\n    { id: "v", label: "Venus" },\n    { id: "e", label: "Earth" },\n    { id: "ma", label: "Mars" },\n  ]}\n/>',
+      composition: ["quiz", "single-answer"]
+    },
+    {
+      title: "Multi-answer with explanations",
+      description: "Multiple correct options + per-option explanations after submit.",
+      code: `<Quiz
+  question="Which planets are gas giants?"
+  selectionMode="multi"
+  options={[
+    { id: "j", label: "Jupiter", correct: true },
+    { id: "v", label: "Venus" },
+    { id: "s", label: "Saturn", correct: true, explanation: "Saturn's atmosphere is mostly H/He." },
+  ]}
+/>`,
+      composition: ["quiz", "multi-answer", "explanation"]
+    }
+  ],
+  ai: {
+    whenToUse: "Render a single self-test question with N preset answers. Vocabulary multiple choice, fact-based questions, code-output predictions, comprehension checks. Use when answers are constrained to a finite set the consumer can author upfront.",
+    whenNotToUse: "Don't use for free-form recall (use Flashcard or Cloze). Don't use for image regions (use ImageOcclusion). Don't use for multi-question quizzes \u2014 Quiz is a single-question primitive; consumers compose their own state to chain multiple instances. Don't use when the answer is graded server-side after submit \u2014 Quiz reveals correctness immediately on submit, no async hook.",
+    commonMistakes: [
+      "Forgetting `correct: true` on any option in multi-select mode \u2014 `allCorrect` will fire as `true` only if picked-set equals correct-set, so a quiz with no correct options reports allCorrect on an empty selection",
+      "Putting the explanation on the wrong option \u2014 explanations are intentionally only shown for `correct` / `incorrect` / `missed` cells (not `unanswered`), so a learner sees the explanation for what they missed, what they got wrong, and what they got right",
+      "Re-mounting the Quiz to reset state \u2014 that works, but it's cheaper to clear the parent's options key (or pass a controlled `selectedIds` prop in a future iteration)",
+      "Long questions or labels exceeding ~60 characters \u2014 line-wrapping inside the option list shrinks the click target. Trim or break at a natural punctuation point"
+    ],
+    relatedComponents: ["flashcard", "cloze", "image-occlusion", "deck", "spaced-repetition", "radio-group", "checkbox"],
+    accessibilityNotes: `The options list declares role="radiogroup" (single mode) or role="group" (multi mode). Native <input type="radio|checkbox"> handles keyboard navigation (arrow keys for radios, tab+space for checkboxes). The status line uses role="status" + aria-live="polite" so screen readers announce correctness after submit. Each option's data-state encodes correctness for theming AND offers a hook for screen-reader-only labels if a future iteration adds them.`,
+    tokenBudget: 360
+  },
+  tags: ["artifact", "study", "quiz", "multiple-choice", "active-recall"]
+};
+
+// src/artifacts/compare-table/compare-table.schema.ts
+var compareTableSchema = {
+  name: "compare-table",
+  displayName: "CompareTable",
+  description: "Side-by-side comparison table. Subjects are columns; attributes are rows; cells render the per-subject value for each attribute. Optional difference highlighting flags cells that diverge from the row's reference. Pure HTML; no heavy peer.",
+  category: "artifact",
+  subcategory: "study",
+  props: [
+    {
+      name: "subjects",
+      type: "object",
+      required: true,
+      description: "Array of { id, label }. Renders as columns; display order matches array order."
+    },
+    {
+      name: "attributes",
+      type: "object",
+      required: true,
+      description: 'Array of { id, label, values }. Renders as rows; `values` is a subjectId \u2192 ReactNode map. Missing keys render as "\u2014".'
+    },
+    {
+      name: "highlightDifferences",
+      type: "boolean",
+      required: false,
+      default: false,
+      description: "When true, cells whose value differs from the row's first non-empty cell get a subtle accent."
+    },
+    {
+      name: "onCellClick",
+      type: "function",
+      required: false,
+      description: "Called with (subjectId, attributeId) when a body cell is clicked."
+    },
+    {
+      name: "className",
+      type: "string",
+      required: false,
+      description: "Additional CSS classes on the outer container."
+    }
+  ],
+  variants: [],
+  slots: [],
+  dependencies: {
+    npm: ["clsx", "tailwind-merge"],
+    internal: ["lib/utils"],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: ["card", "border", "muted", "muted-foreground", "accent", "accent-foreground"],
+  examples: [
+    {
+      title: "Operating system comparison",
+      description: "Three subjects, two attributes, with difference highlighting.",
+      code: '<CompareTable\n  highlightDifferences\n  subjects={[\n    { id: "linux", label: "Linux" },\n    { id: "mac", label: "Mac" },\n    { id: "win", label: "Windows" },\n  ]}\n  attributes={[\n    { id: "kernel", label: "Kernel", values: { linux: "Linux", mac: "Darwin", win: "NT" } },\n    { id: "fs", label: "Default FS", values: { linux: "ext4", mac: "APFS", win: "NTFS" } },\n  ]}\n/>',
+      composition: ["compare-table", "comparison", "feature-matrix"]
+    },
+    {
+      title: "Vocabulary pairs",
+      description: "Two-column term \u2194 translation table.",
+      code: '<CompareTable\n  subjects={[\n    { id: "en", label: "English" },\n    { id: "es", label: "Spanish" },\n  ]}\n  attributes={[\n    { id: "1", label: "Hello", values: { en: "Hello", es: "Hola" } },\n    { id: "2", label: "Thank you", values: { en: "Thank you", es: "Gracias" } },\n  ]}\n/>',
+      composition: ["compare-table", "vocabulary"]
+    }
+  ],
+  ai: {
+    whenToUse: "Compare 2\u20136 subjects across 2\u201320 attributes when the user wants to see same-row differences at a glance. Vocab translations, OS feature matrices, framework comparisons, before/after, drug-vs-drug. Use `highlightDifferences` whenever the row's *divergence* is the message.",
+    whenNotToUse: "Don't use for 1 subject (use a regular description list). Don't use for >6 subjects \u2014 columns shrink past readability; use a card grid instead. Don't use when cells contain rich nested layouts (consider DataTable). Don't use for a single learner-recall task \u2014 use Flashcard, Cloze, or Quiz instead.",
+    commonMistakes: [
+      "Including a value with a subjectId that isn't in the subjects array \u2014 the cell silently doesn't render. The component warns in dev when this happens",
+      'Expecting `highlightDifferences` to compare ReactElement cells \u2014 diff is skipped automatically when either the raw value or the row\'s reference is non-primitive (object). Cells render but never flag as `data-differs="true"`. Stringify upstream if you need diffing on rich content',
+      "Mutating subjects / attributes between renders \u2014 React re-renders fine, but downstream memoization in consumer code may cache stale references. Rebuild the arrays from immutable sources",
+      "Long labels in subject headers (>20 chars) \u2014 they wrap and inflate the row height across the whole table. Use abbreviations + tooltips when needed"
+    ],
+    relatedComponents: ["flashcard", "quiz", "cloze", "data-table", "table"],
+    accessibilityNotes: 'Renders a real <table> with semantic <thead>/<tbody>/<th scope="col|row">/<td>. The first column is sticky so attribute labels stay visible during horizontal scroll on narrow viewports. Each cell carries data-subject-id and data-attribute-id for any consumer-driven aria-label or selection behavior. The diff-highlighted cells rely on color alone today \u2014 pair with a per-row screen-reader-only summary for AA-strict consumers.',
+    tokenBudget: 320
+  },
+  tags: ["artifact", "study", "compare-table", "comparison", "matrix"]
+};
+
+// src/artifacts/deck/deck.schema.ts
+var deckSchema = {
+  name: "deck",
+  displayName: "Deck",
+  description: "Paged sequence of flashcards with optional shuffle, prev/next navigation, a progress bar, and a render slot for per-card SRS rating. Composes Flashcard internally.",
+  category: "artifact",
+  subcategory: "study",
+  props: [
+    {
+      name: "cards",
+      type: "object",
+      required: true,
+      description: "Array of { id, front, back }. Display order matches array order unless `shuffle` is set."
+    },
+    {
+      name: "shuffle",
+      type: "boolean",
+      required: false,
+      default: false,
+      description: "Initial shuffle. Order recomputes only when `cards` identity changes \u2014 not on every prev/next, so the user never gets re-shuffled mid-session."
+    },
+    {
+      name: "ratingSlot",
+      type: "function",
+      required: false,
+      description: "Optional render function called with the current card; renders below the deck. Used to compose SpacedRepetition under each card."
+    },
+    {
+      name: "onCardChange",
+      type: "function",
+      required: false,
+      description: "Called with (index, card) whenever the active card changes (after prev / next)."
+    },
+    {
+      name: "cardWidth",
+      type: "number",
+      required: false,
+      default: 360,
+      description: "Pixel width of the inner Flashcard."
+    },
+    {
+      name: "cardHeight",
+      type: "number",
+      required: false,
+      default: 240,
+      description: "Pixel height of the inner Flashcard."
+    },
+    {
+      name: "className",
+      type: "string",
+      required: false,
+      description: "Additional CSS classes on the outer container."
+    }
+  ],
+  variants: [],
+  slots: [
+    {
+      name: "ratingSlot",
+      description: "Render-prop slot called with the current card; ideal for SpacedRepetition's onRate emission.",
+      required: false
+    }
+  ],
+  dependencies: {
+    npm: ["clsx", "tailwind-merge"],
+    internal: ["lib/utils", "artifacts/flashcard/flashcard"],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: ["card", "background", "muted", "muted-foreground", "primary", "border", "ring"],
+  examples: [
+    {
+      title: "Vocabulary deck with shuffle",
+      description: "Three cards, shuffled on first render.",
+      code: '<Deck\n  shuffle\n  cards={[\n    { id: "1", front: "Hello", back: "Hola" },\n    { id: "2", front: "Thank you", back: "Gracias" },\n    { id: "3", front: "Goodbye", back: "Adi\xF3s" },\n  ]}\n/>',
+      composition: ["deck", "vocabulary"]
+    },
+    {
+      title: "Deck composed with SpacedRepetition rating",
+      description: "Each card surfaces an Anki-style rating row after flip.",
+      code: "<Deck\n  cards={cards}\n  ratingSlot={(card) => (\n    <SpacedRepetition cardId={card.id} onRate={(r) => save(r, card.id)} />\n  )}\n/>",
+      composition: ["deck", "srs"]
+    }
+  ],
+  ai: {
+    whenToUse: "Render an ordered (or shuffled) study session of N flashcards with prev/next navigation and progress feedback. Use when the user is grinding through a deck end-to-end. Pair with SpacedRepetition via `ratingSlot` for Anki-style review sessions.",
+    whenNotToUse: "Don't use for a single card (just render Flashcard directly). Don't use when navigation is non-linear (skip-around, jump-to-id) \u2014 Deck is strictly sequential. Don't use for grading multiple-question quizzes (use Quiz directly + your own state). Don't use when shuffle should be reproducible across sessions \u2014 `Math.random()` is non-seeded; pre-shuffle in your data layer and pass `shuffle={false}`.",
+    commonMistakes: [
+      "Toggling `shuffle` mid-session \u2014 the deck recomputes order and resets to card 1. Set `shuffle` once at mount or pre-shuffle in the consumer's data layer",
+      "Mutating the cards array in place \u2014 internal layout treats `cards` as immutable; spread or rebuild from source on each change",
+      "Card ids that aren't unique \u2014 React's reconciliation depends on the unique id key for Flashcard. Duplicate ids cause stale flip state to leak between cards",
+      "Putting interactive content inside `front` / `back` that's also clickable \u2014 those click events bubble to Flashcard's flip handler. Stop propagation in the inner click handler"
+    ],
+    relatedComponents: ["flashcard", "spaced-repetition", "cloze", "quiz", "progress"],
+    accessibilityNotes: `Prev / Next buttons declare aria-label including current and total positions ("Next card. Currently 3 of 12."). The progress bar is aria-hidden because the same information is in the visible '3 / 12' label and in the button labels. The inner Flashcard owns its own ARIA semantics; flipping it via Enter/Space works while the deck nav buttons remain accessible via tab order.`,
+    tokenBudget: 320
+  },
+  tags: ["artifact", "study", "deck", "flashcard", "session"]
+};
+
+// src/artifacts/spaced-repetition/spaced-repetition.schema.ts
+var spacedRepetitionSchema = {
+  name: "spaced-repetition",
+  displayName: "SpacedRepetition",
+  description: "Anki-style confidence rating row \u2014 four buttons (Again / Hard / Good / Easy) that emit a rating signal. Headless on scheduling: consumers wire SM-2, FSRS, or any other algorithm; this primitive just captures the learner's signal.",
+  category: "artifact",
+  subcategory: "study",
+  props: [
+    {
+      name: "cardId",
+      type: "string",
+      required: true,
+      description: "Identifier of the card being rated. Passed back as the second argument to onRate."
+    },
+    {
+      name: "onRate",
+      type: "function",
+      required: true,
+      description: 'Called with (rating, cardId) when the learner picks a button. Rating is one of "again" | "hard" | "good" | "easy".'
+    },
+    {
+      name: "labels",
+      type: "object",
+      required: false,
+      description: 'Override the default button labels. Defaults: "Again" / "Hard" / "Good" / "Easy". Pass a partial object \u2014 unspecified ratings keep the defaults.'
+    },
+    {
+      name: "className",
+      type: "string",
+      required: false,
+      description: "Additional CSS classes on the outer container."
+    }
+  ],
+  variants: [],
+  slots: [],
+  dependencies: {
+    npm: ["clsx", "tailwind-merge"],
+    internal: ["lib/utils"],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: ["destructive", "secondary", "secondary-foreground", "primary", "accent", "accent-foreground", "foreground", "ring"],
+  examples: [
+    {
+      title: "Anki-default labels with a hand-rolled scheduler",
+      description: "Forward the rating to a consumer-owned interval calculator.",
+      code: "<SpacedRepetition\n  cardId={card.id}\n  onRate={(rating, id) => scheduler.update(id, rating)}\n/>",
+      composition: ["spaced-repetition", "srs"]
+    },
+    {
+      title: "Inside a Deck via ratingSlot",
+      description: "Each card surfaces a rating row beneath it.",
+      code: "<Deck\n  cards={cards}\n  ratingSlot={(card) => (\n    <SpacedRepetition cardId={card.id} onRate={onRate} />\n  )}\n/>",
+      composition: ["spaced-repetition", "deck", "srs"]
+    }
+  ],
+  ai: {
+    whenToUse: "After a Flashcard / Cloze / ImageOcclusion has been revealed, surface a four-button row so the learner self-reports recall quality. Pair with a scheduler (Anki SM-2, FSRS, custom) on the consumer side. Best place: inside Deck's ratingSlot prop.",
+    whenNotToUse: "Don't use as a generic rating widget \u2014 this is study-specific, with semantic Anki labels (Again / Hard / Good / Easy). Don't use when the rating is a continuous value or a star count (use a slider or a star-rating component). Don't use without a scheduler \u2014 the rating is meaningless without something that consumes it to schedule the next review.",
+    commonMistakes: [
+      "Forgetting to wire `onRate` \u2014 the buttons fire but nothing happens. There's no internal scheduler",
+      "Calling SpacedRepetition before the card is revealed \u2014 the user hasn't seen the answer yet, so any rating is a guess. Render after Flashcard's flip event, after Cloze's reveal event, or after Quiz's submit",
+      "Reusing the same cardId across multiple cards in a session \u2014 the consumer's scheduler will misroute interval updates. Pass each card's unique id",
+      'Overriding labels with non-Anki semantics \u2014 "Again / Hard / Good / Easy" map to standard SM-2/FSRS difficulty grades 1\u20134. Custom labels are fine, but the four buckets should still mean roughly forgot / barely / fluent / instant'
+    ],
+    relatedComponents: ["flashcard", "cloze", "image-occlusion", "quiz", "deck"],
+    accessibilityNotes: `Outer container has role="group" with aria-label="Confidence rating". Each button is a real <button> with an aria-label that includes the rating label AND a hint about its effect on the next review ("Again: Couldn't recall \u2014 show this card again soon."). Native button focus + Enter/Space activation handle keyboard interaction.`,
+    tokenBudget: 280
+  },
+  tags: ["artifact", "study", "spaced-repetition", "srs", "anki", "rating"]
+};
+
+export { accordionSchema, alertDialogSchema, alertSchema, arcSchema, aspectRatioSchema, attachmentSchema, avatarSchema, badgeSchema, breadcrumbSchema, buttonSchema, calendarSchema, cardSchema, checkboxSchema, chordSchema, citationSchema, clozeSchema, clusterSchema, codeBlockSchema, collapsibleSchema, colorPickerSchema, comboboxSchema, commandSchema, compareTableSchema, composerSchema, containerSchema, contextMenuSchema, dataTableSchema, datePickerSchema, deckSchema, dendrogramSchema, dialogSchema, drawerSchema, dropdownMenuSchema, dropzoneSchema, emptySchema, errorStateSchema, fileTreeSchema, flashcardSchema, flowchartSchema, formSchema, funnelSchema, ganttSchema, gridSchema, hoverCardSchema, imageOcclusionSchema, inputOTPSchema, inputSchema, labelSchema, loadingIndicatorSchema, loadingSchema, markdownSchema, matrixSchema, menubarSchema, messageActionsSchema, messageListSchema, messageSchema, mindMapSchema, multiComboboxSchema, navigationMenuSchema, orgChartSchema, paginationSchema, popoverSchema, progressSchema, pyramidSchema, quizSchema, radioGroupSchema, reasoningSchema, resizableSchema, sankeySchema, scrollAreaSchema, selectSchema, separatorSchema, sequenceSchema, sheetSchema, sidebarSchema, skeletonSchema, sliderSchema, sonnerSchema, spacedRepetitionSchema, spacerSchema, stackSchema, stepperSchema, suggestionSchema, sunburstSchema, switchSchema, tableSchema, tabsSchema, tagSchema, textareaSchema, timeAxisSchema, timePickerSchema, timelineSchema, toggleGroupSchema, toggleSchema, toolCallSchema, toolbarSchema, tooltipSchema, treeMapSchema, treeSchema, vennSchema };
 //# sourceMappingURL=schemas.js.map
 //# sourceMappingURL=schemas.js.map