@sakaniui/react 0.8.8 → 0.8.9

package/AGENTS.md

@@ -16,8 +16,14 @@ import manifest from '@sakaniui/react/manifest.json';
 const button = manifest.components.find((c) => c.name === 'Button'); // props[], contract.requiredProps
 ```
 Editors can query the same data through the bundled MCP server
-(`npx -y -p @sakaniui/react sakaniui-mcp`): `get_component`, `check_usage`, `get_tokens`, `get_guide`,
-`check_compatibility`, `get_changelog`. If it is connected, call `check_usage` on every component you write.
+(`npx -y -p @sakaniui/react sakaniui-mcp`): `search_components`, `get_component`, `search_icons`,
+`check_code`, `check_usage`, `get_tokens`, `get_guide`, `check_compatibility`, `get_changelog`.
+
+**Start from the example, check before you answer.** Every component has `example`: its imports and the
+element with each required prop filled in, type-checked against the release. Start from it instead of
+writing the element from memory. Never guess an icon name: find it with `search_icons` (icons are
+`IconTrash`, `IconSettings`, ... from `@sakaniui/react/icons`, passed as `icon={IconTrash}`, not
+`icon={<IconTrash />}`). If the server is connected, run `check_code` on every snippet you write.
 
 **Versions.** Every component has `since`, the first release that contained it. The project may have an
 older `@sakaniui/react` installed than the one the manifest describes: if an entry is marked

package/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 All notable changes to `@sakaniui/react` are documented here.
 
+## 0.8.9
+
+Stops assistants from inventing code. Found by testing the MCP server in Claude Code: it validated a
+snippet correctly, then wrote its own example as `icon={<TrashIcon />}` -- an icon that does not exist,
+passed as an element instead of a component.
+
+- **Examples.** Every component and block in `manifest.json` has `example`: the import lines and the
+  element with each required prop filled in with a value of the right shape (an array of `BreadcrumbItem`
+  gets one real item). Prop types are read from the shipped `.d.ts`, and every example is type-checked
+  against the built package; the build fails if one does not compile.
+- **Icon index.** `@sakaniui/react/icon-index.json` lists all 5,184 icons (and their 1,054 filled
+  variants) with Tabler's category and search tags. The build fails if it differs from the exports.
+- **MCP: `search_icons`.** Finds real icon names by meaning ("delete" -> `IconTrash`); common UI intents
+  rank the conventional icon first.
+- **MCP: `check_code`.** Checks a whole snippet as text (it is never run): imports must exist and come
+  from the right entry point, every SakaniUI element needs its required props, values must be allowed,
+  and icon props must be real icon components passed as `icon={IconTrash}`. Errors carry line numbers
+  and suggestions ("TrashIcon is not exported... Did you mean: IconTrash?").
+- **MCP: `check_usage`** now validates icon props too, and `get_component` points at the example and
+  at `search_icons`.
+- Fixed a type error in `KanbanBoardBlock` (drag attributes when dragging is disabled) that was printed
+  during every build.
+
 ## 0.8.8
 
 Audit of the agent contract and MCP server (accuracy, security, versioning).

package/README.md

@@ -115,18 +115,19 @@ up instead of guessing prop names.
 
 Claude Code: `claude mcp add sakaniui -- npx -y -p @sakaniui/react sakaniui-mcp`
 
-Tools: `search_components`, `get_component`, `list_components`, `get_tokens`, `check_usage`
-(validates props against the contract), `get_guide`, `check_compatibility` and `get_changelog`.
+Tools: `search_components`, `get_component` (with a type-checked `example`), `search_icons`,
+`check_code` (checks a whole snippet: imports, required props, values, icon names), `check_usage`,
+`list_components`, `get_tokens`, `get_guide`, `check_compatibility` and `get_changelog`.
 
-- **Read-only.** It reads four fixed files from a `@sakaniui/react` install (package.json, the
-  manifest, AGENTS.md, CHANGELOG.md). It writes nothing, runs nothing, opens no network connection and
+- **Read-only.** It reads five fixed files from a `@sakaniui/react` install (package.json, the
+  manifest, the icon index, AGENTS.md, CHANGELOG.md). Code given to `check_code` is read as text, never run. It writes nothing, runs nothing, opens no network connection and
   takes no file paths. Every tool is marked read-only.
 - **Matches your version.** It finds the `@sakaniui/react` installed in your project (working directory,
   or `--project <dir>`) and flags components your version does not have yet, with the release notes for
   the versions in between (`get_changelog`).
 - **Accurate by construction.** `npm run build:lib` fails if the manifest disagrees with the real build:
-  an export that is not described, a prop that is not declared, a token that is not defined, or anything
-  that looks like a private reference.
+  an export that is not described, a prop that is not declared, an example that does not type-check, an
+  icon name that does not exist, a token that is not defined, or anything that looks like a private reference.
 
 ## Glass & liquid glass
 

package/bin/sakaniui-mcp.mjs

@@ -6,9 +6,10 @@
  *
  * Zero dependencies: speaks newline-delimited JSON-RPC (MCP stdio transport).
  *
- * Read-only by construction. It reads four fixed files (package.json, dist/manifest.json,
- * AGENTS.md, CHANGELOG.md) from a @sakaniui/react install and writes nothing, runs nothing and
- * opens no network connection. No tool takes a path; every tool argument is validated.
+ * Read-only by construction. It reads five fixed files (package.json, dist/manifest.json,
+ * dist/icon-index.json, AGENTS.md, CHANGELOG.md) from a @sakaniui/react install and writes nothing,
+ * runs nothing and opens no network connection. No tool takes a path; every argument is validated.
+ * Code passed to check_code is only read as text, never executed.
  *
  * Version-aware. `npx` may fetch a newer release than the project uses, so the server looks for
  * the project's own installed @sakaniui/react (walking up from --project or the working
@@ -30,7 +31,7 @@ const readJson = (root, rel) => { try { return JSON.parse(readText(root, rel));
 function loadInstall(root) {
   const pkg = readJson(root, 'package.json');
   if (!pkg || pkg.name !== '@sakaniui/react') return null;
-  return { root, version: pkg.version, manifest: readJson(root, 'dist/manifest.json'), guide: readText(root, 'AGENTS.md'), changelog: readText(root, 'CHANGELOG.md') };
+  return { root, version: pkg.version, manifest: readJson(root, 'dist/manifest.json'), icons: readJson(root, 'dist/icon-index.json'), guide: readText(root, 'AGENTS.md'), changelog: readText(root, 'CHANGELOG.md') };
 }
 
 function findProjectInstall() {
@@ -64,6 +65,7 @@ const active = project && project.manifest && schemaOf(project) >= schemaOf(bund
 const manifest = active.manifest;
 const guide = active.guide || bundled.guide || '';
 const changelog = active.changelog || bundled.changelog || '';
+const iconIndex = (active.icons && active.icons.icons) || (bundled.icons && bundled.icons.icons) || [];
 const projectVersion = project ? project.version : null;
 
 /* ---------- versions ---------- */
@@ -152,6 +154,73 @@ function closest(name) {
     .map(([, c]) => c);
 }
 
+/* ---------- icons ---------- */
+const iconNames = new Set();
+for (const i of iconIndex) { iconNames.add(i.name); if (i.filled) iconNames.add(i.filled); }
+const iconWords = (name) => name.replace(/^Icon/, '').replace(/Filled$/, '').replace(/([a-z0-9])([A-Z])/g, '$1 $2').replace(/([A-Za-z])(\d)/g, '$1 $2').toLowerCase();
+
+// The conventional icon for common UI intents, ranked first (tags alone rank e.g. IconHttpDelete above IconTrash for "delete").
+const COMMON = {
+  delete: ['IconTrash'], remove: ['IconTrash', 'IconX'], trash: ['IconTrash'], bin: ['IconTrash'], edit: ['IconPencil', 'IconEdit'], rename: ['IconPencil'],
+  close: ['IconX'], dismiss: ['IconX'], cancel: ['IconX'], add: ['IconPlus'], new: ['IconPlus'], create: ['IconPlus'], plus: ['IconPlus'],
+  search: ['IconSearch'], find: ['IconSearch'], settings: ['IconSettings', 'IconAdjustments'], preferences: ['IconSettings'], menu: ['IconMenu2'],
+  more: ['IconDots', 'IconDotsVertical'], options: ['IconDots', 'IconDotsVertical'], user: ['IconUser'], profile: ['IconUser', 'IconUserCircle'], account: ['IconUserCircle'],
+  home: ['IconHome'], back: ['IconArrowLeft', 'IconChevronLeft'], next: ['IconArrowRight', 'IconChevronRight'], forward: ['IconArrowRight'], previous: ['IconArrowLeft', 'IconChevronLeft'],
+  expand: ['IconChevronDown'], collapse: ['IconChevronUp'], dropdown: ['IconChevronDown'], upload: ['IconUpload'], download: ['IconDownload'], share: ['IconShare'],
+  copy: ['IconCopy'], duplicate: ['IconCopy'], save: ['IconDeviceFloppy'], filter: ['IconFilter'], sort: ['IconArrowsSort'], calendar: ['IconCalendar'], date: ['IconCalendar'],
+  notification: ['IconBell'], notifications: ['IconBell'], bell: ['IconBell'], mail: ['IconMail'], email: ['IconMail'], message: ['IconMessage'], chat: ['IconMessageCircle'],
+  phone: ['IconPhone'], call: ['IconPhone'], logout: ['IconLogout'], signout: ['IconLogout'], login: ['IconLogin'], help: ['IconHelpCircle', 'IconHelp'], info: ['IconInfoCircle'],
+  warning: ['IconAlertTriangle'], error: ['IconAlertCircle'], success: ['IconCircleCheck'], check: ['IconCheck'], done: ['IconCheck'], favorite: ['IconHeart', 'IconStar'],
+  like: ['IconHeart', 'IconThumbUp'], star: ['IconStar'], rating: ['IconStar'], cart: ['IconShoppingCart'], refresh: ['IconRefresh'], reload: ['IconRefresh'], link: ['IconLink'],
+  attach: ['IconPaperclip'], attachment: ['IconPaperclip'], lock: ['IconLock'], password: ['IconLock'], view: ['IconEye'], show: ['IconEye'], hide: ['IconEyeOff'],
+  play: ['IconPlayerPlay'], pause: ['IconPlayerPause'], stop: ['IconPlayerStop'], theme: ['IconSun', 'IconMoon'], dark: ['IconMoon'], light: ['IconSun'],
+  external: ['IconExternalLink'], drag: ['IconGripVertical'], sidebar: ['IconLayoutSidebar'], dashboard: ['IconLayoutDashboard'], analytics: ['IconChartBar'], chart: ['IconChartBar'],
+  money: ['IconCurrencyDollar'], payment: ['IconCreditCard'], card: ['IconCreditCard'], location: ['IconMapPin'], time: ['IconClock'], clock: ['IconClock'], file: ['IconFile'],
+  folder: ['IconFolder'], image: ['IconPhoto'], photo: ['IconPhoto'], video: ['IconVideo'],
+};
+
+function searchIcons(query, limit = 12) {
+  const terms = String(query).toLowerCase().replace(/icon/g, ' ').split(/[^a-z0-9]+/).filter(Boolean);
+  if (!terms.length) return [];
+  const boosted = new Map();
+  for (const t of terms) (COMMON[t] || []).forEach((n, k) => boosted.set(n, Math.max(boosted.get(n) || 0, 40 - k * 5)));
+  return iconIndex
+    .map((i) => {
+      const words = iconWords(i.name).split(' ');
+      const tags = (i.tags || []).map((t) => t.toLowerCase());
+      let s = boosted.get(i.name) || 0;
+      for (const t of terms) {
+        if (words.join(' ') === t) s += 30;
+        else if (words[0] === t) s += 12;
+        else if (words.includes(t)) s += 8;
+        else if (words.some((w) => w.startsWith(t))) s += 4;
+        if (tags.includes(t)) s += 6;
+        else if (tags.some((g) => g.includes(t))) s += 2;
+        if ((i.category || '').toLowerCase() === t) s += 2;
+      }
+      return [s - words.length * 0.1, i];
+    })
+    .filter(([s]) => s > 0.5)
+    .sort((a, b) => b[0] - a[0])
+    .slice(0, limit)
+    .map(([, i]) => i);
+}
+
+/** Checks a value given for an icon prop. Returns an error string, or null. */
+function iconProblem(propName, raw, importedElsewhere = new Set()) {
+  const v = String(raw).trim().replace(/^\{|\}$/g, '').trim();
+  if (/^</.test(v)) {
+    const tag = (/^<\s*([A-Za-z][\w.]*)/.exec(v) || [])[1] || 'Icon';
+    const real = iconNames.has(tag) || importedElsewhere.has(tag) ? tag : (searchIcons(tag, 1)[0] || {}).name;
+    const unknown = real && real !== tag ? ` ${tag} is not a SakaniUI icon either.` : '';
+    return `"${propName}" takes the icon component itself, not an element: write ${propName}={${real || 'IconName'}}, not ${propName}={<${tag} />}.${unknown}${!real ? ' Use search_icons to find the real name.' : ''}`;
+  }
+  if (!/^[A-Za-z_$][\w$]*$/.test(v)) return null; // an expression we cannot judge
+  if (iconNames.has(v) || importedElsewhere.has(v)) return null;
+  const hint = searchIcons(v, 3).map((i) => i.name);
+  return `"${v}" is not a SakaniUI icon.${hint.length ? ` Did you mean: ${hint.join(', ')}?` : ''} Use search_icons to find the real name.`;
+}
+
 const NATIVE = /^(className|style|id|ref|key|children|role|tabIndex|title|hidden|lang|dir|slot|on[A-Z].*|aria-.*|data-.*)$/;
 
 /** Release notes: [{version, body}] newest first, from the CHANGELOG that matches the answering install. */
@@ -162,6 +231,189 @@ function releases() {
   return out.sort((a, b) => cmp(b.version, a.version));
 }
 
+/* ---------- check_code: a small, read-only JSX scanner (the code is never executed) ---------- */
+/** Line number lookup in O(log n): a precomputed index of line starts per code string. */
+function lineIndex(code) {
+  const starts = [0];
+  for (let i = 0; i < code.length; i++) if (code.charCodeAt(i) === 10) starts.push(i + 1);
+  return (pos) => { let lo = 0, hi = starts.length - 1; while (lo < hi) { const mid = (lo + hi + 1) >> 1; if (starts[mid] <= pos) lo = mid; else hi = mid - 1; } return lo + 1; };
+}
+let lineAt = (code, i) => code.slice(0, i).split('\n').length;
+
+function parseImports(code) {
+  const out = [];
+  const re = /import\s+(type\s+)?(?:([A-Za-z_$][\w$]*)\s*,?\s*)?(?:\{([^}]*)\})?\s*from\s*['"]([^'"]+)['"]/g;
+  let m;
+  while ((m = re.exec(code))) {
+    const names = (m[3] || '').split(',').map((x) => x.trim()).filter(Boolean).map((x) => {
+      const typeOnly = /^type\s+/.test(x);
+      const [imported, local] = x.replace(/^type\s+/, '').split(/\s+as\s+/).map((y) => y.trim());
+      return { imported, local: local || imported, typeOnly: typeOnly || !!m[1] };
+    });
+    out.push({ from: m[4], names, line: lineAt(code, m.index), def: m[2] || null });
+  }
+  return out;
+}
+
+/** Reads a balanced {...} starting at code[i] === '{'. Returns the index after the closing brace. */
+function skipBraces(code, i) {
+  let depth = 0;
+  for (; i < code.length; i++) {
+    const ch = code[i];
+    if (ch === '"' || ch === "'" || ch === '`') {
+      const q = ch;
+      for (i++; i < code.length && code[i] !== q; i++) if (code[i] === '\\') i++;
+      continue;
+    }
+    if (ch === '{') depth++;
+    else if (ch === '}') { depth--; if (depth === 0) return i + 1; }
+  }
+  return code.length;
+}
+
+const ATTR_NAME = /[A-Za-z_][\w:.-]*/y;
+
+function parseElements(code, wanted) {
+  const els = [];
+  const re = /<([A-Z][\w]*(?:\.[A-Z][\w]*)?)(?=[\s/>])/g;
+  let m;
+  while ((m = re.exec(code))) {
+    const tag = m[1];
+    if (!wanted(tag)) continue;
+    let i = m.index + m[0].length;
+    const attrs = [];
+    let spread = false;
+    let selfClosing = false;
+    // every pass must move forward; an unterminated attribute ends the element instead of looping
+    for (let guard = 0; i < code.length && guard < 5000; guard++) {
+      while (/\s/.test(code[i])) i++;
+      if (code[i] === '/' && code[i + 1] === '>') { selfClosing = true; i += 2; break; }
+      if (code[i] === '>') { i++; break; }
+      if (code[i] === '<') break; // a new tag before this one closed: malformed, stop here
+      if (code[i] === '{') { const end = skipBraces(code, i); if (/^\{\s*\.\.\./.test(code.slice(i, end))) spread = true; i = end; continue; }
+      ATTR_NAME.lastIndex = i;
+      const nm = ATTR_NAME.exec(code);
+      if (!nm) { i++; continue; }
+      const name = nm[0];
+      i += name.length;
+      while (/\s/.test(code[i])) i++;
+      if (code[i] !== '=') { attrs.push({ name, kind: 'boolean', value: true }); continue; }
+      i++;
+      while (/\s/.test(code[i])) i++;
+      if (code[i] === '"' || code[i] === "'") {
+        const q = code[i];
+        const end = code.indexOf(q, i + 1);
+        if (end === -1) { attrs.push({ name, kind: 'string', value: code.slice(i + 1) }); i = code.length; break; }
+        attrs.push({ name, kind: 'string', value: code.slice(i + 1, end) });
+        i = end + 1;
+      } else if (code[i] === '{') {
+        const end = skipBraces(code, i);
+        const expr = code.slice(i + 1, end - 1).trim();
+        attrs.push({ name, ...classify(expr) });
+        i = end;
+      }
+    }
+    els.push({ tag, attrs, spread, selfClosing, line: lineAt(code, m.index) });
+    if (els.length >= 5000) break;
+    re.lastIndex = Math.max(re.lastIndex, i);
+  }
+  return els;
+}
+
+function classify(expr) {
+  let m;
+  if ((m = /^(['"])([\s\S]*)\1$/.exec(expr))) return { kind: 'string', value: m[2], raw: expr };
+  if ((m = /^`([^`$]*)`$/.exec(expr))) return { kind: 'string', value: m[1], raw: expr };
+  if (/^-?\d+(\.\d+)?$/.test(expr)) return { kind: 'number', value: Number(expr), raw: expr };
+  if (expr === 'true' || expr === 'false') return { kind: 'boolean', value: expr === 'true', raw: expr };
+  if (/^</.test(expr)) return { kind: 'element', raw: expr };
+  if (/^[A-Za-z_$][\w$]*$/.test(expr)) return { kind: 'identifier', value: expr, raw: expr };
+  return { kind: 'expression', raw: expr };
+}
+
+const TYPE_LIKE = /(Props|Type|Variant|Size|Item|Option|Datum|Column|Link|Plan|Post|Action|Step|Image|Author|Change|Data|Tab|Color|Category|Job|Member|Testimonial|Transaction)$/;
+
+function checkCode(code) {
+  lineAt = ((idx) => (_c, pos) => idx(pos))(lineIndex(code));
+  const errors = [];
+  const warnings = [];
+  const imports = parseImports(code);
+  const importedFrom = new Map(); // local name -> module
+  for (const imp of imports) for (const n of imp.names) importedFrom.set(n.local, imp.from);
+  const importedElsewhere = new Set([...importedFrom].filter(([, from]) => !from.startsWith('@sakaniui/react')).map(([n]) => n));
+
+  for (const imp of imports) {
+    if (!imp.from.startsWith('@sakaniui/react')) continue;
+    const entry = imp.from;
+    if (!['@sakaniui/react', '@sakaniui/react/blocks', '@sakaniui/react/icons'].includes(entry)) {
+      if (imp.names.length) errors.push({ line: imp.line, message: `"${entry}" has no named exports. Import components from @sakaniui/react, blocks from @sakaniui/react/blocks and icons from @sakaniui/react/icons.` });
+      continue;
+    }
+    if (imp.def) errors.push({ line: imp.line, message: `${entry} has no default export; use a named import: import { ${imp.def} } from '${entry}';` });
+    for (const n of imp.names) {
+      if (n.typeOnly) continue;
+      const c = byName.get(n.imported.toLowerCase());
+      const isUtility = manifest.utilities?.some((u) => u.name === n.imported);
+      if (entry === '@sakaniui/react/icons') {
+        if (!iconNames.has(n.imported)) {
+          const hint = searchIcons(n.imported, 3).map((i) => i.name);
+          errors.push({ line: imp.line, message: `${n.imported} is not exported by @sakaniui/react/icons.${hint.length ? ` Did you mean: ${hint.join(', ')}?` : ''}` });
+        }
+        continue;
+      }
+      if (c && c.name !== n.imported) { errors.push({ line: imp.line, message: `${n.imported} has the wrong casing; the export is ${c.name}.` }); continue; }
+      if (entry === '@sakaniui/react/blocks') {
+        if (!c || c.kind !== 'block') errors.push({ line: imp.line, message: c ? `${n.imported} is a component: import it from @sakaniui/react.` : `${n.imported} is not a SakaniUI block.` });
+        continue;
+      }
+      if (c && c.kind === 'block') { errors.push({ line: imp.line, message: `${n.imported} is a block: import it from @sakaniui/react/blocks.` }); continue; }
+      if (!c && !isUtility) {
+        if (TYPE_LIKE.test(n.imported)) continue; // most likely a type export
+        const near = closest(n.imported);
+        errors.push({ line: imp.line, message: `${n.imported} is not exported by @sakaniui/react.${near.length ? ` Did you mean: ${near.join(', ')}?` : ''} Use search_components.` });
+      }
+      if (c && inInstalled(c) === false) errors.push({ line: imp.line, message: `${c.name} was added in ${c.since}; the project has ${projectVersion}.` });
+    }
+  }
+
+  // elements: anything imported from @sakaniui, plus manifest names used without an import
+  const isSakani = (tag) => importedFrom.get(tag)?.startsWith('@sakaniui/react') || (!importedFrom.has(tag) && byName.has(tag.toLowerCase()) && byName.get(tag.toLowerCase()).name === tag);
+  const elements = parseElements(code, isSakani);
+  for (const el of elements) {
+    const c = byName.get(el.tag.toLowerCase());
+    if (!c) continue;
+    const at = (message) => ({ line: el.line, message: `<${el.tag}>: ${message}` });
+    if (!importedFrom.has(el.tag)) warnings.push(at(`not imported. Add: import { ${c.name} } from '${c.import}';`));
+    const given = new Map(el.attrs.map((a) => [a.name, a]));
+    if (!el.selfClosing) given.set('children', { kind: 'expression' });
+    for (const r of c.contract.requiredProps) {
+      if (given.has(r)) continue;
+      if (el.spread) warnings.push(at(`required prop "${r}" is not written out (it may come from the spread).`));
+      else errors.push(at(`missing required prop "${r}".`));
+    }
+    const known = new Map(c.props.map((p) => [p.name, p]));
+    for (const a of el.attrs) {
+      const p = known.get(a.name);
+      if (!p) { if (!NATIVE.test(a.name) && a.name !== 'key' && a.name !== 'ref') warnings.push(at(`"${a.name}" is not a ${c.name} prop (it only works if it is a native attribute).`)); continue; }
+      if (p.values && ['string', 'number', 'boolean'].includes(a.kind) && !p.values.includes(a.value)) {
+        errors.push(at(`${a.name}=${JSON.stringify(a.value)} is not allowed. Use one of: ${p.values.map((x) => JSON.stringify(x)).join(', ')}.`));
+      }
+      if (p.type === 'IconComponent') {
+        if (a.kind === 'string') errors.push(at(`"${a.name}" takes an icon component, not a string: ${a.name}={IconName}.`));
+        else if (a.kind === 'element' || a.kind === 'identifier') {
+          const e = iconProblem(a.name, a.raw, importedElsewhere);
+          if (e) errors.push(at(e));
+          else if (a.kind === 'identifier' && iconNames.has(a.value) && importedFrom.get(a.value) !== '@sakaniui/react/icons') warnings.push(at(`${a.value} is not imported. Add: import { ${a.value} } from '@sakaniui/react/icons';`));
+        }
+      }
+    }
+  }
+  if (!elements.length && !imports.some((i) => i.from.startsWith('@sakaniui/react'))) warnings.push({ line: 1, message: 'No SakaniUI imports or elements found in this code.' });
+  const out = { ok: errors.length === 0, checkedElements: elements.length, errors, warnings };
+  const note = versionNote(); if (note) out.versionNote = note;
+  return out;
+}
+
 const READ_ONLY = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
 
 /* ---------- tools ---------- */
@@ -194,6 +446,8 @@ const tools = {
       const c = byName.get(n.value.toLowerCase());
       if (!c) return fail(`No component named "${n.value}". Did you mean: ${closest(n.value).join(', ') || '(none close)'}? Use search_components.`);
       const out = { ...c, note: 'Native HTML attributes (className, style, aria-*, event handlers) are also accepted on the root element.' };
+      if (c.example) out.exampleNote = 'Start from `example`: it is type-checked against this release. Replace the placeholder text and values; keep the prop names and shapes.';
+      if (c.props.some((p) => p.type === 'IconComponent')) out.iconNote = 'Icon props take the component itself (icon={IconTrash}), not an element. The example uses IconStar as a placeholder: find the real icon with search_icons.';
       if (inInstalled(c) === false) out.availableInInstalled = false;
       const note = versionNote();
       if (note) out.versionNote = note;
@@ -255,6 +509,7 @@ const tools = {
         if (p.values && (typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean') && !p.values.includes(v)) {
           errors.push(`"${k}" = ${JSON.stringify(v)} is not allowed. Use one of: ${p.values.map((x) => JSON.stringify(x)).join(', ')}.`);
         }
+        if (p.type === 'IconComponent' && typeof v === 'string') { const e = iconProblem(k, v); if (e) errors.push(e); }
       }
       if (c.contract.requiresAccessibleName && !errors.length) warnings.push('This control has no visible text of its own: keep its accessible-name prop set.');
       const out = { component: c.name, ok: errors.length === 0, errors, warnings };
@@ -301,6 +556,28 @@ const tools = {
       return text(pick.map((r) => `## ${r.version}\n\n${r.body}`).join('\n\n'));
     },
   },
+  search_icons: {
+    description: 'Find real icon names (Tabler set, exported from @sakaniui/react/icons) by meaning, e.g. "delete", "settings", "arrow right". Never guess an icon name: only names returned here exist.',
+    inputSchema: { type: 'object', properties: { query: { type: 'string' }, limit: { type: 'number' } }, required: ['query'] },
+    run(args) {
+      const q = strArg(args, 'query', { required: true }); if (q.err) return fail(q.err);
+      if (!iconIndex.length) return fail('The icon index is not available in this install.');
+      const limit = Number.isInteger(args.limit) ? Math.min(Math.max(args.limit, 1), 30) : 12;
+      const hits = searchIcons(q.value, limit).map((i) => { const o = { name: i.name }; if (i.filled) o.filled = i.filled; if (i.category) o.category = i.category; if (i.tags) o.tags = i.tags.slice(0, 5); return o; });
+      if (!hits.length) return text(`No icon matches "${q.value}". Try a simpler word (e.g. "delete" rather than "remove item").`);
+      return text({ import: "import { IconName } from '@sakaniui/react/icons';", usage: 'icon={IconName} (the component, not <IconName />)', icons: hits });
+    },
+  },
+  check_code: {
+    description: 'Check a JSX/TSX snippet you wrote: imports from @sakaniui/react (and /blocks, /icons) must exist, every SakaniUI element must have its required props, prop values must be allowed, and icon props must be real icon components passed as components. The code is only read, never run. Run it on every snippet before you answer.',
+    inputSchema: { type: 'object', properties: { code: { type: 'string', description: 'The snippet, including its import lines.' } }, required: ['code'] },
+    run(args) {
+      const code = args.code;
+      if (typeof code !== 'string' || !code.trim()) return fail('"code" must be a non-empty string.');
+      if (code.length > 50000) return fail('"code" is too long (max 50,000 characters).');
+      return text(checkCode(code));
+    },
+  },
   get_guide: {
     description: 'The AGENTS.md guide (principles, token rules, when nothing fits, glass, icons, per-component "why / when not to use", checklist). Pass a section number or heading text to get just that section; omit for the section list.',
     inputSchema: { type: 'object', properties: { section: { type: 'string' } } },