@sakaniui/react 0.8.9 → 0.8.11

package/AGENTS.md

@@ -16,9 +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`): `search_components`, `get_component`, `search_icons`,
+(`npx -y @sakaniui/mcp`): `search_components`, `get_component`, `search_icons`,
 `check_code`, `check_usage`, `get_tokens`, `get_guide`, `check_compatibility`, `get_changelog`.
 
+**Object props have a shape.** A prop such as `columns`, `items`, `options`, `plans` or `data` takes an array
+of objects with exactly the fields listed under the prop's `shape` (required ones must be present, and
+`keyof T` means "a field of your own data type"). `check_code` verifies the field names of inline literals.
+Components with a pattern the types do not teach carry `recipes`: code that compiles.
+
 **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
@@ -206,7 +211,11 @@ Format: **Use for** · **Why it is built this way** · **Not for / instead**.
 ### Content and data
 - **Card** — a container surface for a unit of content, optionally with actions. Not a layout wrapper for
   everything.
-- **Table** — dense, comparable records. **StatCard** — one headline metric with trend. **ListItem** — a
+- **Table** — dense, comparable records. `Table<T>` is generic: every column's `key` must be a field of
+  your row type `T` (`keyof T & string`), so a column that is not data (a delete button, a menu) still
+  needs a key: give the row type an optional `never` field (`actions?: never`) and render the control in
+  `render`. Inventing a key that is not on the row type does not compile (see `recipes` in
+  `get_component("Table")` for code that does). **StatCard** — one headline metric with trend. **ListItem** — a
   row in a list. **Charts** — pick by question: trend over time → Line/Area; compare categories → Bar;
   part of whole → Pie/Donut (few slices only); progress to a target → Radial; compare several measures →
   Radar; drop-off → Funnel; intensity across two dimensions → Heatmap.

package/CHANGELOG.md

@@ -2,6 +2,66 @@
 
 All notable changes to `@sakaniui/react` are documented here.
 
+## 0.8.11
+
+Found by asking Claude Code, with the published 0.8.10 MCP server, to add a delete button to a table row:
+every tool call was correct and `IconButton` was used properly, but it put the button in a new `Table`
+column with `key: 'actions'`, which does not compile (`key` must be a field of the row type). The
+contract only said `columns: TableColumn<T>[]`.
+
+- **Object props now have a `shape`** in `manifest.json`: the fields of `TableColumn<T>`, `BreadcrumbItem`,
+  `PricingPlan`, `SelectOption`, chart data and 58 more (63 props), read from the shipped type
+  definitions, generics kept as declared (`key: keyof T & string`).
+- **`recipes`**: code for patterns the types do not teach, compiled on every build. First one: a `Table`
+  column that is not data (a delete button, a menu). The build also checks the opposite, that a column
+  key which is not on the row type really does not compile.
+- **MCP `check_code` checks inline object literals** against the shape: an unknown field (`title` for
+  `label`, `pct` for `percent`, with a suggestion), a missing required field (with the item index), and,
+  for a `Table`, a column `key` that is not a field of the `rows` written next to it. Spreads, identifiers
+  and anything it cannot read are left alone (0 errors on 685 real elements in three apps).
+- `AGENTS.md` explains the generic `Table` rule and the new `shape` and `recipes`.
+
+## 0.8.10
+
+Readiness release: everything below was found by testing the package the way a new user, an editor
+and an AI agent would, and every fix is now covered by a check that fails the build.
+
+**Installing the library**
+- **Fixed: installing `@sakaniui/react` installed Next.js.** The `geist` and `@fontsource-variable/geist`
+  font packages were runtime dependencies, though the library never loads them, and `geist` requires
+  Next.js as a peer, so every app (Vite included) got Next.js 16. Both are now dev-only; the only runtime
+  dependency is `recharts`. Load Geist yourself if you want it (`@fontsource-variable/geist`); otherwise
+  the system font is used, as before.
+- **Fixed: missing type definitions.** `dist/lib/` was left out of the generated `.d.ts` files, so
+  `LiquidGlass`, `LiquidBackdrop`, `HoverGroup`, `useHoverHighlight`, `useLiquidGlass`, `getContrastColor`
+  and `iconStrokeWidth` had no types: `<LiquidBackdrop />` compiled without its required `src`. The build
+  now fails if any relative import in a shipped `.d.ts` does not resolve.
+- **Fixed docs: `style.css` is required.** The README and the website's Installation page only imported
+  `tokens.css`, which leaves components unstyled. Both now import both stylesheets.
+
+**The MCP server**
+- **New package `@sakaniui/mcp`** (about 190 kB, no dependencies): `npx -y @sakaniui/mcp` starts in
+  about 2 s on a first run. Through `@sakaniui/react` it took ~30 s and ~675 MB, long enough for an editor
+  to give up. The copy in `@sakaniui/react` still works.
+- **`check_code`: no false positives** on 685 real elements across three apps (it reported 77). Aliased
+  and default imports, code inside template strings, native attributes and the non-icon exports of
+  `@sakaniui/react/icons` are handled; it still catches every deliberate mistake in the test set.
+- **Versions per prop and per value.** Each prop added after its component has its own `since` (for
+  example `Switch.variant`, 0.8.4), and values added later are listed in `valuesSince`. `since` now means
+  "first release you could import it", taken from the package's public exports at every release (the
+  social icons are 0.8.6, not 0.3.0). `check_code`, `check_usage` and `get_component` flag props and
+  values the project's installed version does not have.
+- **Invented props are errors.** A prop that is neither the component's own nor an HTML attribute (React's
+  own attribute list now ships in `manifest.json` as `nativeAttributes`) fails `check_code` and
+  `check_usage`, with the real prop list and a suggestion (`leftIcon` -> "did you mean leadingIcon?").
+  Real HTML attributes (`placeholder`, `href`, `name`...) pass silently; `color` gets a note that it does
+  not style the component.
+- **Protocol:** negotiates a supported protocol version, answers `resources/list`, `prompts/list` and
+  batches, exits when the editor disconnects (flushing replies first), and survives a closed pipe.
+  `get_guide` accepts `query`. Tested on Node 18, 20, 22 and 26, with the official MCP SDK client and the
+  MCP Inspector, and documented for Windows (`cmd /c npx ...`).
+- Removed an unresolvable `$schema` link from `manifest.json`.
+
 ## 0.8.9
 
 Stops assistants from inventing code. Found by testing the MCP server in Claude Code: it validated a

package/README.md

@@ -43,12 +43,33 @@ accepts Lucide or Tabler React icons. See `THIRD_PARTY_NOTICES.md` for the MIT l
 npm install @sakaniui/react
 ```
 
-Then import the tokens once at your app's entry point, and any component from the package root:
+Then import the two stylesheets once, at your app's entry point (both are required: `tokens.css` defines
+the design tokens, `style.css` styles the components), and use any component from the package root:
 
 ```tsx
 import '@sakaniui/react/tokens.css';
+import '@sakaniui/react/style.css';
+
+import { Button } from '@sakaniui/react';
+
+export function Example() {
+  return <Button variant="primary">Get started</Button>;
+}
+```
+
+Requires React 19. Typography is set in **Geist**; load the font yourself if you want it (otherwise the
+system font is used):
+
+```bash
+npm install @fontsource-variable/geist
 ```
 
+```tsx
+import '@fontsource-variable/geist';
+```
+
+Charts (`AreaChart`, `BarChart`, ...) use `recharts`, which is installed with the package.
+
 > **Building with AI?** `AGENTS.md` (shipped in this package) explains *why* components behave as they do and what to do when nothing fits. Index for agents: https://www.sakaniui.com/llms.txt
 
 ## Quick start (contributing / browsing the source)
@@ -108,15 +129,20 @@ up instead of guessing prop names.
 ```json
 {
   "mcpServers": {
-    "sakaniui": { "command": "npx", "args": ["-y", "-p", "@sakaniui/react", "sakaniui-mcp"] }
+    "sakaniui": { "command": "npx", "args": ["-y", "@sakaniui/mcp"] }
   }
 }
 ```
 
-Claude Code: `claude mcp add sakaniui -- npx -y -p @sakaniui/react sakaniui-mcp`
+Claude Code: `claude mcp add sakaniui -- npx -y @sakaniui/mcp`
+
+On Windows, launch `npx` through `cmd /c` (`"command": "cmd", "args": ["/c", "npx", "-y", "@sakaniui/mcp"]`,
+or `claude mcp add sakaniui -- cmd /c npx -y @sakaniui/mcp`). Needs Node.js 18 or later.
+
+The server is its own tiny package, [`@sakaniui/mcp`](https://www.npmjs.com/package/@sakaniui/mcp) (about 1 MB, starts in a couple of seconds; it does not install the component library). The copy bundled in `@sakaniui/react` (`npx -y -p @sakaniui/react sakaniui-mcp`) still works but downloads far more.
 
 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`,
+`check_code` (checks a whole snippet: imports, required props, values, icon names, and the field names of object props such as table columns), `check_usage`,
 `list_components`, `get_tokens`, `get_guide`, `check_compatibility` and `get_changelog`.
 
 - **Read-only.** It reads five fixed files from a `@sakaniui/react` install (package.json, the

package/bin/sakaniui-mcp.mjs

@@ -2,7 +2,7 @@
 /**
  * SakaniUI MCP server -- lets an AI editor/agent look up the design system instead of guessing.
  *
- *   npx -y -p @sakaniui/react sakaniui-mcp [--project <dir>]
+ *   npx -y @sakaniui/mcp [--project <dir>]     (or: npx -y -p @sakaniui/react sakaniui-mcp)
  *
  * Zero dependencies: speaks newline-delimited JSON-RPC (MCP stdio transport).
  *
@@ -47,7 +47,8 @@ function findProjectInstall() {
   return null;
 }
 
-const bundled = loadInstall(ownRoot);
+// inside @sakaniui/react the data sits next to bin/; inside @sakaniui/mcp it is copied into data/
+const bundled = loadInstall(fs.existsSync(path.join(ownRoot, 'dist', 'manifest.json')) ? ownRoot : path.join(ownRoot, 'data'));
 if (!bundled || !bundled.manifest) {
   process.stderr.write('sakaniui-mcp: dist/manifest.json not found. Run `npm run build:lib` (or install a published version).\n');
   process.exit(1);
@@ -68,6 +69,22 @@ const changelog = active.changelog || bundled.changelog || '';
 const iconIndex = (active.icons && active.icons.icons) || (bundled.icons && bundled.icons.icons) || [];
 const projectVersion = project ? project.version : null;
 
+// The HTML attributes React accepts (shipped in the manifest since 0.8.10; older manifests use the fallback list).
+const nativeAttrs = new Set(manifest.nativeAttributes || []);
+const NATIVE = { test: (n) => /^(aria-|data-)/.test(n) || /^on[A-Z]/.test(n) || n === 'key' || n === 'ref' || n === 'children' || (nativeAttrs.size ? nativeAttrs.has(n) : NATIVE_FALLBACK.test(n)) };
+/** What to say about a prop the component does not declare: an error when nothing accepts it, else a note. */
+function unknownProp(c, name) {
+  if (NATIVE.test(name)) {
+    // a real HTML attribute (placeholder, href, name, defaultChecked...): passed to the element, and fine.
+    // `color` is the one people mistake for a styling prop: it does not colour the component.
+    return name === 'color' ? { level: 'warning', message: `"color" is not a ${c.name} prop: it is the old HTML colour attribute and does not change the component's colours. Use the component's own props, or design tokens (get_tokens).` } : null;
+  }
+  // close spellings, plus the usual synonyms (leftIcon -> leadingIcon, onChange vs onValueChange is left to the list)
+  const canon = (x) => x.toLowerCase().replace(/left|start|before|prefix/g, 'leading').replace(/right|end|after|suffix/g, 'trailing').replace(/colou?r|tone|kind|type/g, 'variant');
+  const near = c.props.map((p) => p.name).filter((p) => similar(p, name) || canon(p) === canon(name));
+  return { level: 'error', message: `"${name}" is not a ${c.name} prop${near.length ? ` (did you mean ${near.map((x) => `"${x}"`).join(', ')}?)` : ''}. ${c.name} accepts: ${c.props.map((p) => p.name).join(', ') || 'no props of its own'}.` };
+}
+
 /* ---------- versions ---------- */
 const SEMVER = /^\d+\.\d+\.\d+/;
 const parse = (v) => String(v).split('-')[0].split('.').map(Number);
@@ -93,6 +110,15 @@ function inInstalled(c, installed = projectVersion) {
   return cmp(c.since, installed) <= 0;
 }
 
+/** Is this prop (or this value of it) in the project's install? Returns a message when it is not. */
+function propTooNew(c, p, value, installed = projectVersion) {
+  if (!installed) return null;
+  if (p.since && cmp(p.since, installed) > 0) return `"${p.name}" was added to ${c.name} in ${p.since}; the project has ${installed}, where it does not exist. Upgrade (npm install @sakaniui/react@latest) or leave it out.`;
+  const vs = p.valuesSince && typeof value === 'string' ? p.valuesSince[value] : null;
+  if (vs && cmp(vs, installed) > 0) return `${p.name}=${JSON.stringify(value)} was added in ${vs}; the project has ${installed}, where it does not exist.`;
+  return null;
+}
+
 /* ---------- helpers ---------- */
 const byName = new Map(manifest.components.map((c) => [c.name.toLowerCase(), c]));
 const brief = (c) => {
@@ -144,6 +170,16 @@ function distance(a, b) {
   return d[a.length][b.length];
 }
 
+/** `pct` for `percent`, `desc` for `description`: same first letter, every letter in order. */
+function isAbbreviation(short, full) {
+  const a = short.toLowerCase(), b = full.toLowerCase();
+  if (a.length < 2 || a.length >= b.length || a[0] !== b[0]) return false;
+  let i = 0;
+  for (const ch of b) if (ch === a[i]) i++;
+  return i === a.length;
+}
+const similar = (a, b) => distance(a.toLowerCase(), b.toLowerCase()) <= 2 || isAbbreviation(a, b) || isAbbreviation(b, a);
+
 function closest(name) {
   const n = name.toLowerCase();
   return manifest.components
@@ -157,6 +193,7 @@ function closest(name) {
 /* ---------- icons ---------- */
 const iconNames = new Set();
 for (const i of iconIndex) { iconNames.add(i.name); if (i.filled) iconNames.add(i.filled); }
+const iconOtherExports = new Set(((active.icons && active.icons.other) || (bundled.icons && bundled.icons.other)) || []);
 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").
@@ -207,7 +244,7 @@ function searchIcons(query, limit = 12) {
 }
 
 /** Checks a value given for an icon prop. Returns an error string, or null. */
-function iconProblem(propName, raw, importedElsewhere = new Set()) {
+function iconProblem(propName, raw, importedElsewhere = new Set(), localNames = new Set()) {
   const v = String(raw).trim().replace(/^\{|\}$/g, '').trim();
   if (/^</.test(v)) {
     const tag = (/^<\s*([A-Za-z][\w.]*)/.exec(v) || [])[1] || 'Icon';
@@ -216,12 +253,15 @@ function iconProblem(propName, raw, importedElsewhere = new Set()) {
     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;
+  if (iconNames.has(v) || importedElsewhere.has(v) || localNames.has(v)) return null;
+  // a local name (alias, parameter, constant): the import line was already checked, and we cannot see the rest
+  if (!/^Icon[A-Z0-9]/.test(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-.*)$/;
+// Attributes every component forwards to its root element. A prop outside this list and the contract is worth a warning.
+const NATIVE_FALLBACK = /^(className|style|id|ref|key|children|role|tabIndex|title|hidden|lang|dir|slot|on[A-Z].*|aria-.*|data-.*|href|target|rel|download|name|type|value|defaultValue|checked|defaultChecked|disabled|required|readOnly|placeholder|htmlFor|form|autoFocus|autoComplete|autoCapitalize|spellCheck|inputMode|pattern|min|max|step|minLength|maxLength|rows|cols|multiple|accept|src|srcSet|alt|width|height|loading|draggable|tabindex|ariaLabel)$/;
 
 /** Release notes: [{version, body}] newest first, from the CHANGELOG that matches the answering install. */
 function releases() {
@@ -333,14 +373,38 @@ function classify(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) {
+/** Replaces the contents of template literals with spaces (newlines kept): code shown inside a string is not code. */
+function blankTemplates(code) {
+  let out = '';
+  for (let i = 0; i < code.length; i++) {
+    const ch = code[i];
+    if (ch === '`') {
+      let j = i + 1, depth = 0;
+      for (; j < code.length; j++) {
+        if (code[j] === '\\') { j++; continue; }
+        if (code[j] === '$' && code[j + 1] === '{') { depth++; j++; continue; }
+        if (code[j] === '}' && depth > 0) { depth--; continue; }
+        if (code[j] === '`' && depth === 0) break;
+      }
+      out += '`' + code.slice(i + 1, j).replace(/[^\n]/g, ' ') + '`';
+      i = j;
+    } else out += ch;
+  }
+  return out;
+}
+
+function checkCode(source) {
+  const code = blankTemplates(source);
   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);
+  for (const imp of imports) { for (const n of imp.names) importedFrom.set(n.local, imp.from); if (imp.def) importedFrom.set(imp.def, imp.from); }
   const importedElsewhere = new Set([...importedFrom].filter(([, from]) => !from.startsWith('@sakaniui/react')).map(([n]) => n));
+  // anything the snippet declares itself (const Icon = ..., function X, class Y) or aliases: not ours to judge
+  const localNames = new Set([...code.matchAll(/\b(?:const|let|var|function|class)\s+([A-Za-z_$][\w$]*)/g)].map((m) => m[1]));
+  for (const imp of imports) for (const n of imp.names) if (n.local !== n.imported) localNames.add(n.local);
 
   for (const imp of imports) {
     if (!imp.from.startsWith('@sakaniui/react')) continue;
@@ -355,7 +419,7 @@ function checkCode(code) {
       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)) {
+        if (!iconNames.has(n.imported) && !iconOtherExports.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(', ')}?` : ''}` });
         }
@@ -383,6 +447,7 @@ function checkCode(code) {
     const c = byName.get(el.tag.toLowerCase());
     if (!c) continue;
     const at = (message) => ({ line: el.line, message: `<${el.tag}>: ${message}` });
+    if (inInstalled(c) === false && !importedFrom.has(el.tag)) errors.push(at(`${c.name} was added in ${c.since}; the project has ${projectVersion}, where it does not exist.`));
     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' });
@@ -394,16 +459,18 @@ function checkCode(code) {
     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) { const u = unknownProp(c, a.name); if (u) (u.level === 'error' ? errors : warnings).push(at(u.message)); 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(', ')}.`));
       }
+      { const tooNew = propTooNew(c, p, a.kind === 'string' ? a.value : undefined); if (tooNew) errors.push(at(tooNew)); }
+      for (const m of checkShape(c, p, a, new Map(el.attrs.map((x) => [x.name, x])))) errors.push(at(m));
       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);
+          const e = iconProblem(a.name, a.raw, importedElsewhere, localNames);
           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';`));
+          else if (a.kind === 'identifier' && iconNames.has(a.value) && !importedFrom.has(a.value) && !localNames.has(a.value)) warnings.push(at(`${a.value} is not imported. Add: import { ${a.value} } from '@sakaniui/react/icons';`));
         }
       }
     }
@@ -414,6 +481,89 @@ function checkCode(code) {
   return out;
 }
 
+/* ---------- literal shapes: field names inside inline object literals ---------- */
+/** Splits `text` at top-level commas (ignores commas inside brackets, braces, parentheses and strings). */
+function splitTopLevel(text) {
+  const parts = [];
+  let depth = 0, start = 0, quote = null;
+  for (let i = 0; i < text.length && parts.length < 2000; i++) {
+    const ch = text[i];
+    if (quote) { if (ch === '\\') i++; else if (ch === quote) quote = null; continue; }
+    if (ch === '"' || ch === "'" || ch === '`') { quote = ch; continue; }
+    if (ch === '{' || ch === '[' || ch === '(') depth++;
+    else if (ch === '}' || ch === ']' || ch === ')') depth--;
+    else if (ch === ',' && depth === 0) { parts.push(text.slice(start, i)); start = i + 1; }
+  }
+  parts.push(text.slice(start));
+  return parts.map((x) => x.trim()).filter(Boolean);
+}
+
+/** The keys written in an object literal `{ a: 1, 'b': 2, c, ...d }`. spread: it also contains `...x`. */
+function objectKeys(literal) {
+  const inner = literal.trim().slice(1, -1);
+  const keys = []; let spread = false;
+  for (const entry of splitTopLevel(inner)) {
+    if (entry.startsWith('...')) { spread = true; continue; }
+    const m = /^(?:'([^']+)'|"([^"]+)"|([A-Za-z_$][\w$]*))\s*(?::|\(|$)/.exec(entry);
+    if (m) keys.push(m[1] || m[2] || m[3]);
+    else spread = true; // computed key or something we cannot read: do not judge this object
+  }
+  return { keys, spread };
+}
+
+/** The object literals in an inline `[ {...}, {...} ]` (or a single `{...}`). Null when it is not an inline literal. */
+function inlineObjects(raw, collection) {
+  const t = raw.trim();
+  if (collection === 'array') {
+    if (!(t.startsWith('[') && t.endsWith(']'))) return null;
+    const items = splitTopLevel(t.slice(1, -1));
+    if (items.some((x) => !x.startsWith('{') || !x.endsWith('}'))) return items.filter((x) => x.startsWith('{') && x.endsWith('}')).length ? items.filter((x) => x.startsWith('{') && x.endsWith('}')) : null;
+    return items;
+  }
+  return t.startsWith('{') && t.endsWith('}') ? [t] : null;
+}
+
+/** Checks inline object literals against the prop's `shape`. Returns messages. */
+function checkShape(c, prop, attr, siblings) {
+  const sh = prop.shape;
+  if (!sh || attr.kind !== 'expression' || !attr.raw) return [];
+  const objs = inlineObjects(attr.raw, sh.collection);
+  if (!objs || !objs.length) return [];
+  const out = [];
+  const known = new Map(sh.fields.map((f) => [f.name, f]));
+  const list = sh.fields.map((f) => f.name + (f.required ? '' : '?')).join(', ');
+  objs.forEach((lit, idx) => {
+    const { keys, spread } = objectKeys(lit);
+    const where = sh.collection === 'array' ? `${prop.name}[${idx}]` : prop.name;
+    for (const k of keys) {
+      if (!known.has(k)) {
+        const near = sh.fields.map((f) => f.name).filter((f) => similar(f, k));
+        out.push(`${where}: "${k}" is not a field of ${sh.type}${near.length ? ` (did you mean "${near[0]}"?)` : ''}. Fields: ${list}.`);
+      }
+    }
+    if (!spread) for (const f of sh.fields) if (f.required && !keys.includes(f.name)) out.push(`${where}: missing required field "${f.name}" of ${sh.type}. Fields: ${list}.`);
+  });
+  // `key: keyof T`: the key must be a field of the rows given next to it (T[] sibling), when both are written inline
+  const keyField = sh.fields.find((f) => /^keyof T\b/.test(f.type));
+  if (keyField && sh.typeParameters && sh.typeParameters[0] === 'T') {
+    const rowsProp = c.props.find((p) => p.type === 'T[]');
+    const rowsAttr = rowsProp && siblings.get(rowsProp.name);
+    const rowObjs = rowsAttr && rowsAttr.kind === 'expression' ? inlineObjects(rowsAttr.raw || '', 'array') : null;
+    if (rowObjs && rowObjs.length) {
+      const rowKeys = new Set();
+      let rowsOpen = false;
+      for (const r of rowObjs) { const o = objectKeys(r); o.keys.forEach((k) => rowKeys.add(k)); if (o.spread) rowsOpen = true; }
+      if (!rowsOpen) {
+        for (const lit of objs) {
+          const kv = new RegExp(`(?:^|[{,\\s])${keyField.name}\\s*:\\s*['"]([^'"]+)['"]`).exec(lit);
+          if (kv && !rowKeys.has(kv[1])) out.push(`${prop.name}: ${keyField.name} "${kv[1]}" is not a field of the ${rowsProp.name} (${[...rowKeys].join(', ')}). It must be a key of the row type; for a column that is not data, add an optional field to the row type (see the recipe in get_component ${c.name}).`);
+        }
+      }
+    }
+  }
+  return out;
+}
+
 const READ_ONLY = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
 
 /* ---------- tools ---------- */
@@ -446,9 +596,22 @@ 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.props.some((p) => p.shape)) out.shapeNote = 'A prop with a `shape` takes an object (or an array of objects) with exactly those fields; `required` fields must be present. In a generic shape, `keyof T & string` means the value must be a field of your own data type.';
+      if (c.recipes && c.recipes.length) out.recipeNote = 'See `recipes`: patterns the types alone do not teach, compiled against this release.';
       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;
+      if (projectVersion) {
+        out.props = c.props.map((p) => {
+          const tooNew = propTooNew(c, p);
+          const newerValues = p.valuesSince ? Object.entries(p.valuesSince).filter(([, v]) => cmp(v, projectVersion) > 0).map(([k]) => k) : [];
+          if (!tooNew && !newerValues.length) return p;
+          const q = { ...p };
+          if (tooNew) q.availableInInstalled = false;
+          if (newerValues.length) q.valuesNotInInstalled = newerValues;
+          return q;
+        });
+      }
       const note = versionNote();
       if (note) out.versionNote = note;
       if (inInstalled(c) === false) out.warning = `${c.name} was added in ${c.since} but the project has ${projectVersion}. Do not use it without upgrading (npm install @sakaniui/react@latest).`;
@@ -505,11 +668,12 @@ const tools = {
       for (const r of c.contract.requiredProps) if (!Object.hasOwn(props, r)) errors.push(`Missing required prop "${r}".`);
       for (const [k, v] of Object.entries(props)) {
         const p = known.get(k);
-        if (!p) { if (!NATIVE.test(k)) warnings.push(`"${k}" is not a ${c.name} prop in the manifest (it would only work if it is a native attribute).`); continue; }
+        if (!p) { const u = unknownProp(c, k); if (u) (u.level === 'error' ? errors : warnings).push(u.message); continue; }
         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); }
+        const tooNew = propTooNew(c, p, v); if (tooNew) errors.push(tooNew);
       }
       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 };
@@ -580,9 +744,10 @@ const tools = {
   },
   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' } } },
+    inputSchema: { type: 'object', properties: { section: { type: 'string', description: 'A section number ("3") or words from its heading ("icons").' } } },
     run(args) {
-      const s0 = strArg(args, 'section'); if (s0.err) return fail(s0.err);
+      // agents sometimes call it with `query`; treat that as the section
+      const s0 = strArg(args.section === undefined && args.query !== undefined ? { section: args.query } : args, 'section'); if (s0.err) return fail(s0.err);
       if (!guide) return fail('AGENTS.md is not available in this install.');
       const parts = guide.split(/^(?=## )/m).filter((p) => p.startsWith('## '));
       const heads = parts.map((p) => p.split('\n')[0].replace(/^## /, ''));
@@ -595,45 +760,71 @@ const tools = {
 };
 
 /* ---------- JSON-RPC over stdio ---------- */
-const send = (msg) => process.stdout.write(JSON.stringify({ jsonrpc: '2.0', ...msg }) + '\n');
+// Protocol versions this server implements; the client's is used when it is one of them.
+const PROTOCOL_VERSIONS = ['2025-11-25', '2025-06-18', '2025-03-26', '2024-11-05'];
 
+let stdoutClosed = false;
+process.stdout.on('error', () => { stdoutClosed = true; process.exit(0); }); // the client went away (EPIPE)
+const write = (payload) => { if (!stdoutClosed) process.stdout.write(JSON.stringify(payload) + '\n'); };
+const reply = (id, body) => ({ jsonrpc: '2.0', id, ...body });
+
+/** Handles one message. Returns the response, or null for notifications. */
 function handle(msg) {
-  if (!msg || typeof msg !== 'object' || Array.isArray(msg)) return send({ id: null, error: { code: -32600, message: 'Invalid request' } });
+  if (!msg || typeof msg !== 'object' || Array.isArray(msg)) return reply(null, { error: { code: -32600, message: 'Invalid request' } });
   const { id, method, params } = msg;
   const isRequest = id !== undefined && id !== null;
+  if (typeof method !== 'string') return isRequest ? reply(id, { error: { code: -32600, message: 'Invalid request: method must be a string' } }) : null;
+  if (!isRequest) return null; // notifications (initialized, cancelled, ...) need no answer
   try {
     switch (method) {
       case 'initialize': {
         const note = versionNote();
-        return send({ id, result: {
-          protocolVersion: params?.protocolVersion || '2025-06-18',
-          capabilities: { tools: {} },
-          serverInfo: { name: 'sakaniui', version: refVersion },
-          instructions: `SakaniUI ${refVersion}${projectVersion ? ` (project has ${projectVersion})` : ''}. Read-only reference. Look components up with search_components / get_component before writing JSX, validate with check_usage, use only tokens from get_tokens, and read get_guide when nothing fits.${note ? ` ${note}` : ''}`,
+        const asked = params && typeof params.protocolVersion === 'string' ? params.protocolVersion : null;
+        return reply(id, { result: {
+          protocolVersion: asked && PROTOCOL_VERSIONS.includes(asked) ? asked : PROTOCOL_VERSIONS[0],
+          capabilities: { tools: { listChanged: false } },
+          serverInfo: { name: 'sakaniui', title: 'SakaniUI', version: refVersion },
+          instructions: `SakaniUI ${refVersion}${projectVersion ? ` (project has ${projectVersion})` : ''}. Read-only reference. Look components up with search_components / get_component and start from their \`example\`; find icon names with search_icons (never guess them); run check_code on every snippet before you answer; style anything beyond props with the design tokens from get_tokens (CSS variables), not hard-coded colours or utility classes the project may not have; read get_guide when nothing fits.${note ? ` ${note}` : ''}`,
         } });
       }
       case 'ping':
-        return send({ id, result: {} });
+        return reply(id, { result: {} });
       case 'tools/list':
-        return send({ id, result: { tools: Object.entries(tools).map(([name, t]) => ({ name, description: t.description, inputSchema: t.inputSchema, annotations: READ_ONLY })) } });
+        return reply(id, { result: { tools: Object.entries(tools).map(([name, t]) => ({ name, description: t.description, inputSchema: t.inputSchema, annotations: READ_ONLY })) } });
       case 'tools/call': {
         const t = typeof params?.name === 'string' && Object.hasOwn(tools, params.name) ? tools[params.name] : null;
-        if (!t) return send({ id, error: { code: -32602, message: `Unknown tool: ${String(params?.name).slice(0, 60)}` } });
+        if (!t) return reply(id, { error: { code: -32602, message: `Unknown tool: ${String(params?.name).slice(0, 60)}` } });
         const args = params.arguments;
-        if (args !== undefined && args !== null && (typeof args !== 'object' || Array.isArray(args))) return send({ id, result: fail('Tool arguments must be an object.') });
-        return send({ id, result: t.run(args || {}) });
+        if (args !== undefined && args !== null && (typeof args !== 'object' || Array.isArray(args))) return reply(id, { result: fail('Tool arguments must be an object.') });
+        return reply(id, { result: t.run(args || {}) });
       }
+      // Some clients ask for these even when only tools are offered; an empty list is the polite answer.
+      case 'resources/list': return reply(id, { result: { resources: [] } });
+      case 'resources/templates/list': return reply(id, { result: { resourceTemplates: [] } });
+      case 'prompts/list': return reply(id, { result: { prompts: [] } });
+      case 'logging/setLevel': return reply(id, { result: {} });
       default:
-        if (isRequest) send({ id, error: { code: -32601, message: `Method not found: ${String(method).slice(0, 60)}` } });
+        return reply(id, { error: { code: -32601, message: `Method not found: ${method.slice(0, 60)}` } });
     }
   } catch (e) {
-    if (isRequest) send({ id, error: { code: -32603, message: String(e?.message || e) } });
+    return reply(id, { error: { code: -32603, message: String(e?.message || e) } });
   }
 }
 
-readline.createInterface({ input: process.stdin }).on('line', (line) => {
+const rl = readline.createInterface({ input: process.stdin, crlfDelay: Infinity });
+rl.on('line', (line) => {
   if (!line.trim()) return;
   let msg;
-  try { msg = JSON.parse(line); } catch { return send({ id: null, error: { code: -32700, message: 'Parse error' } }); }
-  handle(msg);
+  try { msg = JSON.parse(line); } catch { return write(reply(null, { error: { code: -32700, message: 'Parse error' } })); }
+  if (Array.isArray(msg)) { // a batch (older protocol versions): answer with one array
+    if (!msg.length) return write(reply(null, { error: { code: -32600, message: 'Invalid request: empty batch' } }));
+    const out = msg.map(handle).filter(Boolean);
+    if (out.length) write(out);
+    return;
+  }
+  const r = handle(msg);
+  if (r) write(r);
 });
+// the editor closed the connection: exit instead of lingering as an orphan process
+// (flush first: on macOS and Windows, writes to a pipe are asynchronous)
+rl.on('close', () => { if (stdoutClosed) process.exit(0); else process.stdout.write('', () => process.exit(0)); });