@vjdesigns/vjdesigns-ui 0.0.0-stage → 2.0.0

package/dist/ai/llms.txt

@@ -0,0 +1,196 @@
+# @vjdesigns/vjdesigns-ui
+
+> Accessible React 19 component library: WCAG 2.2 AA verified (axe on every story, a contrast check on every color pair), 31 languages with right-to-left support, themeable with any brand color (auto-adjusted to stay accessible), tree-shakable, no runtime dependencies besides React.
+
+- Install: `npm install @vjdesigns/vjdesigns-ui` (peer: react, react-dom 18 or 19).
+- Import the stylesheet once: `import "@vjdesigns/vjdesigns-ui/dist/vjdesigns-ui.css";`
+- Import components from the package root: `import { Button, Field, Input } from "@vjdesigns/vjdesigns-ui";`
+- Theme: wrap the app in `<Theme brand="blue" | "purple" | ... | "#hex" mode="light" | "dark" accent="brand" | "lime" | "#hex">`.
+- Language: `<LocaleProvider locale="es" messages={es}>` with `import es from "@vjdesigns/vjdesigns-ui/locales/es"`.
+- Forms: wrap each control in `Field` (label, hint, error, required); validate with `useFormValidation` + `ErrorSummary`.
+- Style with the props (variant, tone, size) and the --color-*, --space-*, --radius-* CSS variables; don't override internal class names.
+
+## Docs
+
+- [Full reference](llms-full.txt): setup, theming, languages, form validation, and every component's props, subcomponents, and examples.
+- [Registry](registry.json): the same as JSON (components, props, hooks, utilities, guides).
+- MCP server: `npx -p @vjdesigns/vjdesigns-ui vjdesigns-ui-mcp` (tools: list_components, get_component, search_docs, get_guide).
+
+## Data-display
+
+- [Accordion](llms-full.txt#accordion): A vertically stacked set of headings that each reveal a section of content.
+- [Avatar](llms-full.txt#avatar): A person's picture, with a fallback chain of image, initials, then a user icon.
+- [AvatarGroup](llms-full.txt#avatargroup): Overlapping stack of avatars in a labelled `role="group"`.
+- [Badge](llms-full.txt#badge): A small, non-interactive status or label pill.
+- [BadgeAnchor](llms-full.txt#badgeanchor): Pins a count, dot, or short label to a corner of its child.
+- [Card](llms-full.txt#card): A soft, rounded surface that groups related content.
+- [Carousel](llms-full.txt#carousel): A row of slides that scroll horizontally with CSS scroll snap (so touch, trackpad, and swipe work natively), plus Previous / Next buttons, optional slide picker indicators, and optional autoplay with a Pause / Play button.
+- [Chip](llms-full.txt#chip): A compact pill for tags, filters, and selections.
+- [ChipGroup](llms-full.txt#chipgroup): Lays out chips with a gap and wraps them.
+- [Code](llms-full.txt#code): Inline code inside running text, e.g. a prop name or a command.
+- [CodeBlock](llms-full.txt#codeblock): A block of source code with a header (language and filename), a copy button, optional line numbers, highlighted lines, and diff gutters.
+- [DataGrid](llms-full.txt#datagrid): An interactive data table (WAI-ARIA APG "Data Grid"): sortable columns (with Shift for multi-column sorts), search filtering, single or multiple row selection, pagination, and a full keyboard model.
+- [EmptyState](llms-full.txt#emptystate): A friendly, centered block for "no data", "no results", "error", and first-run moments.
+- [Image](llms-full.txt#image): A native `<img>` in a frame that reserves its aspect ratio, shows a placeholder while loading, fades the picture in, and falls back gracefully on errors (`fallbackSrc`, then a `fallback` box that keeps the `alt` text as its accessible name).
+- [List](llms-full.txt#list): A semantic list (`<ul>` or `<ol>`) with styled markers and rich items.
+- [Stat](llms-full.txt#stat): A big, bold number with a label, for dashboards and box scores: points, revenue, completion rates.
+- [StatGroup](llms-full.txt#statgroup): A responsive row or grid of `Stat`s, such as a player's box-score line.
+- [Table](llms-full.txt#table): Semantic data table.
+- [Timeline](llms-full.txt#timeline): A vertical or horizontal sequence of events or steps, rendered as an ordered list.
+- [TreeView](llms-full.txt#treeview): A hierarchical list (WAI-ARIA Tree View pattern) for file explorers, org charts, and nested categories.
+- [VirtualList](llms-full.txt#virtuallist): A list that renders only the items in view, so tens of thousands of rows scroll smoothly.
+
+## Feedback
+
+- [Alert](llms-full.txt#alert): An inline, in-page message: info, success, warning, danger, or neutral.
+- [Banner](llms-full.txt#banner): A full-width, page-level strip for announcements, promos, cookie notices, trial reminders, maintenance windows, and connection status.
+- [CircularProgress](llms-full.txt#circularprogress): Ring-shaped progress indicator with rounded caps and an optional center slot.
+- [ErrorSummary](llms-full.txt#errorsummary): The list of a form's errors, shown above it after a failed submit: a danger `Alert` whose items link to their fields (activating one moves focus to the field).
+- [Progress](llms-full.txt#progress): Linear progress bar.
+- [ProgressSegments](llms-full.txt#progresssegments): Stacked bar made of labeled parts, with a legend (e.g. storage usage).
+- [Skeleton](llms-full.txt#skeleton): A soft, rounded placeholder shown while content loads.
+- [SkeletonAvatar](llms-full.txt#skeletonavatar): A placeholder the exact size and shape of an `Avatar`.
+- [SkeletonCircle](llms-full.txt#skeletoncircle): A circular placeholder in `Avatar` sizes (`SkeletonAvatar` with `shape="circle"`).
+- [SkeletonGroup](llms-full.txt#skeletongroup): Wraps a loading region so screen readers get one announcement instead of one per placeholder.
+- [SkeletonText](llms-full.txt#skeletontext): Lines of placeholder text, sized like real `Text` or `Heading` content so nothing jumps when the text arrives.
+- [Spinner](llms-full.txt#spinner): An indeterminate loading indicator.
+- [Toast](llms-full.txt#toast): The toast card: a raised, rounded surface with a tone icon in a tinted circle, a bold title, a description, an optional action, and a close button.
+- [ToastProvider](llms-full.txt#toastprovider): Renders the toast viewport (in a portal) and provides `useToast()`.
+
+## Forms
+
+- [Calendar](llms-full.txt#calendar): A month grid for picking a date or a date range, following the WAI-ARIA date picker grid pattern: arrow keys move by day and week, Home/End to the week's edges, PageUp/PageDown by month (with Shift, by year), and Enter or Space selects.
+- [CheckBox](llms-full.txt#checkbox): A checkbox with a label and an optional description.
+- [CheckBoxGroup](llms-full.txt#checkboxgroup): A labelled set of checkboxes sharing one `string[]` value.
+- [ColorInput](llms-full.txt#colorinput): A pill field showing a swatch and the color value; pressing it opens a `ColorPicker` in a `Popover` (a non-modal dialog on the shared overlay layer stack: Escape and outside presses close it, focus returns to the field).
+- [ColorPicker](llms-full.txt#colorpicker): An inline color picker: a 2D saturation / brightness area, a hue slider, an optional opacity slider, a text field, optional preset swatches, and an eyedropper (when the browser supports it).
+- [Combobox](llms-full.txt#combobox): An editable combobox with a list of suggestions (WAI-ARIA APG Combobox, "list autocomplete" with a listbox popup).
+- [DatePicker](llms-full.txt#datepicker): A date field: type a date in the locale's short format (or ISO), or press the calendar button to pick one from a `Calendar` in a popup dialog.
+- [DateRangePicker](llms-full.txt#daterangepicker): A date range field: two text fields (start and end) typed in the locale's short format, plus a calendar button that opens a range `Calendar` (two months by default) in a modal popup.
+- [DateTimePicker](llms-full.txt#datetimepicker): A date and a time together: a `DatePicker` and a `TimePicker` side by side, with one value, "YYYY-MM-DDTHH:mm" (the format of a native `datetime-local` input, with no time zone).
+- [Field](llms-full.txt#field): Wraps one form control with a label, hint, and error message, and wires them together: `<label for>`, `aria-describedby`, `aria-invalid`, `aria-errormessage`, `required`, and `disabled` all flow to the control through `FieldContext`.
+- [FieldError](llms-full.txt#fielderror): Error message for a Field, with a leading decorative error icon so the state isn't conveyed by color alone.
+- [FieldHint](llms-full.txt#fieldhint): Help text for a Field.
+- [FieldLabel](llms-full.txt#fieldlabel): The label of a Field.
+- [FieldProvider](llms-full.txt#fieldprovider): Provides `FieldContext` without rendering any markup, for fully custom layouts built from `FieldLabel`, `FieldHint`, and `FieldError`.
+- [Fieldset](llms-full.txt#fieldset): Group mode of Field: a `<fieldset>` with a `<legend>`, for a set of related controls (RadioGroup, CheckBoxGroup, or native radios and checkboxes).
+- [FileUpload](llms-full.txt#fileupload): File picker with drag and drop, validation, and a file list.
+- [Input](llms-full.txt#input): A single-line text field built on the native `<input>`.
+- [NumberInput](llms-full.txt#numberinput): A numeric text field following the WAI-ARIA spinbutton pattern.
+- [PasswordInput](llms-full.txt#passwordinput): A password field built on `Input`, with a show/hide toggle, a Caps Lock warning, an optional strength meter, and an optional requirements checklist.
+- [PinInput](llms-full.txt#pininput): A one-time-code or PIN entry shown as a row of cells.
+- [Radio](llms-full.txt#radio): A single option in a `RadioGroup`: a native radio (visually hidden but focusable) with a custom ring-and-dot indicator and a clickable label.
+- [RadioCard](llms-full.txt#radiocard): A large, card-style radio option.
+- [RadioGroup](llms-full.txt#radiogroup): A set of mutually exclusive options.
+- [Rating](llms-full.txt#rating): An editable star (or custom icon) rating, built on real native radios (visually hidden but focusable, sharing one `name`) inside `role="radiogroup"`.
+- [RatingDisplay](llms-full.txt#ratingdisplay): A read-only rating: a row of icons with fractional fill, exposed to assistive tech as a single `role="img"` named "Rated 4.5 out of 5", optionally followed by the value ("4.5 / 5") and a review count.
+- [SearchForm](llms-full.txt#searchform): A `<form role="search">` landmark around a `SearchInput`, so screen reader users can jump straight to search.
+- [SearchInput](llms-full.txt#searchinput): A search field built on `Input`: `type="search"`, a search icon, a clear button, and pill rounding by default.
+- [SegmentedControl](llms-full.txt#segmentedcontrol): Single-choice segmented control.
+- [Select](llms-full.txt#select): Styled native `<select>`.
+- [Slider](llms-full.txt#slider): Pick a number, or a `[start, end]` range, on a pill track.
+- [Switch](llms-full.txt#switch): An on/off toggle for settings that take effect immediately.
+- [TagInput](llms-full.txt#taginput): A text field that turns entries into removable tags (chips).
+- [Textarea](llms-full.txt#textarea): Multi-line text field.
+- [TimePicker](llms-full.txt#timepicker): A time field: type a time in almost any form ("2:30 pm", "1430", "230p", "14h30", the locale's own format), or pick one from a list of times `step` minutes apart.
+- [ToggleButton](llms-full.txt#togglebutton): A button that stays pressed or unpressed (`<button type="button" aria-pressed>`), for on/off options like Bold or "Show starters only".
+- [ToggleGroup](llms-full.txt#togglegroup): A set of toggle buttons (`role="group"`, or `role="toolbar"`) sharing one value.
+
+## Layout
+
+- [Box](llms-full.txt#box): Box: the polymorphic base building block.
+- [Container](llms-full.txt#container): Centers content with a max width and responsive side gutters.
+- [Divider](llms-full.txt#divider): A line that separates content, horizontally or vertically, with an optional inline label.
+- [Flex](llms-full.txt#flex): Full flexbox container: direction (fixed or responsive), wrapping, alignment on both axes, line distribution, and token-based gaps.
+- [Grid](llms-full.txt#grid): A CSS grid container.
+- [HStack](llms-full.txt#hstack): A horizontal Stack (`direction="row"`).
+- [ResizablePanels](llms-full.txt#resizablepanels): Panels split by draggable handles: a sidebar and a main area, an editor and a preview, nested in either direction.
+- [ScrollArea](llms-full.txt#scrollarea): A scrolling region with slim, on-brand scrollbars that work the same in every browser.
+- [Stack](llms-full.txt#stack): One-dimensional flex layout.
+- [VStack](llms-full.txt#vstack): A vertical Stack (`direction="column"`).
+
+## Navigation
+
+- [Breadcrumbs](llms-full.txt#breadcrumbs): A trail of links showing where the current page sits in the site hierarchy.
+- [ContextMenu](llms-full.txt#contextmenu): A menu that opens at the pointer on right-click (or a long press on touch screens), for actions on the thing under the pointer.
+- [Link](llms-full.txt#link): Accessible text link.
+- [Menu](llms-full.txt#menu): A dropdown menu of actions or options, opened from a button (WAI-ARIA APG "Menu Button" and "Menu" patterns).
+- [Navbar](llms-full.txt#navbar): The top header of an app or site.
+- [Pagination](llms-full.txt#pagination): Page navigation: a `<nav>` landmark with a list of pill page buttons, Previous/Next arrows, optional First/Last, and gaps for long ranges.
+- [Sidebar](llms-full.txt#sidebar): App side navigation.
+- [SkipLink](llms-full.txt#skiplink): Bypass link (WCAG 2.4.1) that stays visually hidden until it receives keyboard focus, then springs in as a high-contrast pill at the top start corner of the viewport, above every other layer.
+- [SkipLinks](llms-full.txt#skiplinks): Groups several skip links (for example navigation, search, and main content) as a list.
+- [Stepper](llms-full.txt#stepper): Multi-step progress indicator for wizards and checkout flows, rendered as an ordered list in a labelled group (or a `nav` when steps are clickable).
+- [Tabs](llms-full.txt#tabs): Tabs root.
+
+## Overlays
+
+- [CommandPalette](llms-full.txt#commandpalette): A modal command menu: a search field over a filtered, grouped list of commands, opened with a global hotkey (Cmd/Ctrl+K by default).
+- [ConfirmModal](llms-full.txt#confirmmodal): A ready-made confirmation (`role="alertdialog"`) built on `Modal`.
+- [Drawer](llms-full.txt#drawer): A panel that slides in from an edge of the screen: navigation, filters, details, or a mobile bottom sheet.
+- [HoverCard](llms-full.txt#hovercard): A preview card that opens while the pointer rests on a link or button, or while it has keyboard focus: a player's profile behind their name, a page preview behind a link.
+- [Modal](llms-full.txt#modal): An accessible modal dialog (WAI-ARIA APG "Dialog (Modal)" pattern).
+- [Popover](llms-full.txt#popover): A non-modal dialog anchored to a trigger, for interactive content: short forms, profile cards, settings, pickers.
+- [Tooltip](llms-full.txt#tooltip): A short, non-interactive label or description that appears on hover and on keyboard focus.
+- [TooltipProvider](llms-full.txt#tooltipprovider): Optional.
+
+## Primitives
+
+- [Button](llms-full.txt#button): The library's primary action control.
+- [ButtonGroup](llms-full.txt#buttongroup): Groups related buttons (`role="group"`).
+- [Display](llms-full.txt#display): Hero-sized heading: `Heading` with `level={1}`, `size="6xl"`, and `weight="black"` by default.
+- [Eyebrow](llms-full.txt#eyebrow): Short uppercase overline above a heading, in the display font.
+- [Heading](llms-full.txt#heading): Athletic display heading in `--font-display`: bold, tight, high contrast.
+- [Icon](llms-full.txt#icon): Inline SVG icon.
+- [IconButton](llms-full.txt#iconbutton): A square (or circular, by default) button that shows only an icon.
+- [Kbd](llms-full.txt#kbd): A single keyboard key, rendered as a native `<kbd>` styled like a physical key cap.
+- [KbdShortcut](llms-full.txt#kbdshortcut): A key combination or sequence.
+- [Text](llms-full.txt#text): Friendly body text in `--font-body`.
+
+## Utilities
+
+- [LocaleProvider](llms-full.txt#localeprovider): Sets the language of every component inside: built-in labels and screen-reader text, date and number formats, plurals, and writing direction.
+- [Portal](llms-full.txt#portal): Renders children at the end of document.body (or `container`) so overlays escape parent overflow and stacking contexts.
+- [Theme](llms-full.txt#theme): Applies a brand palette, accent, and/or color mode to everything inside it, through `data-brand`, `data-accent`, and `data-theme` (and, for hex colors, the generated custom properties inline).
+- [VisuallyHidden](llms-full.txt#visuallyhidden): Hides content visually while keeping it available to screen readers.
+
+## Hooks
+
+- [useResolvedElement](llms-full.txt#useresolvedelement): Returns the element behind `source` as state, re-checking ref objects after every commit of the calling component.
+- [useControllableState](llms-full.txt#usecontrollablestate): Supports both controlled (`value` + `onChange`) and uncontrolled (`defaultValue`) usage with one API.
+- [useDismiss](llms-full.txt#usedismiss): Closes floating UI on Escape or on a press outside the given elements.
+- [useFloatingPosition](llms-full.txt#usefloatingposition): Positions a floating element (Tooltip, Popover, Menu, Select listbox) next to an anchor.
+- [useFocusTrap](llms-full.txt#usefocustrap): Keeps Tab / Shift+Tab focus inside `container` while active, and restores focus when it deactivates (WCAG 2.1.2, 2.4.3).
+- [useFormReset](llms-full.txt#useformreset): Calls `onReset` when the form that contains `target`'s element is reset (`<button type="reset">` or `form.reset()`).
+- [useFormValidation](llms-full.txt#useformvalidation): Form validation built on the browser's own constraints (`required`, `type="email"`, `min`, `maxLength`, `pattern`, ...) plus your own `rules`, with the messages in the current language.
+- [useInertOutside](llms-full.txt#useinertoutside): Makes everything outside `elements` inert while `active`.
+- [useParentOverlayLayer](llms-full.txt#useparentoverlaylayer): The id of the nearest enclosing overlay layer, or null at the page level.
+- [useOverlayLayer](llms-full.txt#useoverlaylayer): Registers an overlay on the shared layer stack while `active`.
+- [useScrollLock](llms-full.txt#usescrolllock): Locks page scrolling while `active`.
+- [useMergedRef](llms-full.txt#usemergedref): A callback ref that writes to every given ref (callback or object), stable while the refs are.
+- [useMediaQuery](llms-full.txt#usemediaquery): Whether a CSS media query matches, kept in sync as the viewport or user preferences change.
+- [useResponsiveValue](llms-full.txt#useresponsivevalue): Resolves a `Responsive<T>` value (a single value, or `{ base, sm, md, ...
+- [useDisclosure](llms-full.txt#usedisclosure): Open/closed state for anything that shows and hides (a Modal, Drawer, Popover, a collapsible section), with stable handlers.
+- [useToggle](llms-full.txt#usetoggle): Cycles through values: `[false, true]` by default (a boolean toggle), or any list (`["list", "grid"]`).
+- [useDebouncedCallback](llms-full.txt#usedebouncedcallback): A function that waits until calls stop for `wait` ms, then runs once with the last arguments.
+- [useThrottledCallback](llms-full.txt#usethrottledcallback): A function that runs at most once every `wait` ms: the first call runs right away, and the last call made during the wait runs when it ends.
+- [useDebouncedValue](llms-full.txt#usedebouncedvalue): The value, updated only after it stops changing for `wait` ms.
+- [useInterval](llms-full.txt#useinterval): Calls `callback` every `delay` ms while `delay` is a number; pass `null` to pause.
+- [useTimeout](llms-full.txt#usetimeout): Calls `callback` once, `delay` ms after mount (or after `delay` changes); pass `null` to not schedule it.
+- [usePrevious](llms-full.txt#useprevious): The value from before its last change (undefined until it first changes).
+- [useLocalStorage](llms-full.txt#uselocalstorage): State saved in `localStorage` under `key`: it survives reloads and stays in sync across every component using the key and across browser tabs.
+- [useSessionStorage](llms-full.txt#usesessionstorage): Like `useLocalStorage`, in `sessionStorage`: kept until the tab closes.
+- [useClipboard](llms-full.txt#useclipboard): Copies text to the clipboard, with a `copied` flag that resets after `timeout` ms.
+- [useHotkeys](llms-full.txt#usehotkeys): Keyboard shortcuts for the whole page (or one element).
+- [useEventListener](llms-full.txt#useeventlistener): Adds an event listener and removes it on unmount.
+- [useClickOutside](llms-full.txt#useclickoutside): Calls `handler` when a pointer press or a focus move lands outside the returned ref's element (and outside any `ignore` elements).
+- [useIntersection](llms-full.txt#useintersection): Whether an element is in view (IntersectionObserver).
+- [useElementSize](llms-full.txt#useelementsize): An element's content-box size, kept current as it resizes (ResizeObserver).
+- [useHydrated](llms-full.txt#usehydrated): False during server rendering and hydration, true after.
+- [useReducedMotion](llms-full.txt#usereducedmotion): True when the user asked the system to reduce motion.
+- [useColorScheme](llms-full.txt#usecolorscheme): The system color scheme, `"light"` or `"dark"`, kept in sync (`"light"` during server rendering).
+- [useOnline](llms-full.txt#useonline): Whether the browser has a network connection, kept in sync (true during server rendering).
+- [useDocumentVisibility](llms-full.txt#usedocumentvisibility): `"visible"` or `"hidden"` (another tab, minimized window), kept in sync.
+- [useViewportSize](llms-full.txt#useviewportsize): The viewport's width and height in CSS pixels, kept in sync (0 × 0 during server rendering).
+- [useVirtualizer](llms-full.txt#usevirtualizer): Headless list virtualization: renders only the items in view (plus `overscan`), so lists of 100,000 rows stay fast.
+- [useFillSlot](llms-full.txt#usefillslot): True inside a container that provides `FillSlotContext`.

package/dist/ai/mcp-server.mjs

@@ -0,0 +1,212 @@
+#!/usr/bin/env node
+// A minimal MCP server (stdio, JSON-RPC 2.0, no dependencies) that answers
+// questions about this library from the generated registry.json next to it.
+// Copied to dist/ai/ by scripts/build-ai-docs.mjs; run with:
+//
+//   npx -p @vjdesigns/vjdesigns-ui vjdesigns-ui-mcp
+//
+// Tools: list_components, get_component, search_docs, get_guide.
+
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { createInterface } from "node:readline";
+import { fileURLToPath } from "node:url";
+
+const registry = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), "registry.json"), "utf8"));
+
+/* ---- Formatting ---- */
+
+const propLine = (p) => {
+  const flags = [p.required ? "required" : "", p.default !== undefined ? `default ${p.default}` : "", p.deprecated ? "deprecated" : ""]
+    .filter(Boolean)
+    .join(", ");
+  const desc = (p.description ?? "").replace(/\s+/g, " ").trim();
+  return `- \`${p.name}\`: \`${p.type}\`${flags ? ` (${flags})` : ""}${desc ? `. ${desc}` : ""}`;
+};
+
+function componentDoc(c) {
+  const out = [`# ${c.name}`, "", c.import, "", `Category: ${c.category}${c.storybook ? ` · Storybook: ${c.storybook}` : ""}`, ""];
+  if (c.description) out.push(c.description, "");
+  out.push("## Props", "", ...(c.props.length ? c.props.map(propLine) : ["- (none of its own)"]));
+  if (c.nativeElement) out.push(`- Plus every native \`<${c.nativeElement}>\` attribute, spread onto the root.`);
+  for (const s of c.subcomponents ?? []) {
+    out.push("", `## ${s.name}`, "");
+    if (s.description) out.push(s.description, "");
+    out.push(...s.props.map(propLine));
+    if (s.nativeElement) out.push(`- Plus every native \`<${s.nativeElement}>\` attribute.`);
+  }
+  if (c.stories?.length) {
+    out.push("", "## Examples (Storybook stories)", "", ...c.stories.map((s) => `- ${s.name}${s.description ? `: ${s.description.replace(/\s+/g, " ")}` : ""}`));
+  }
+  return out.join("\n");
+}
+
+const firstSentence = (text = "") => {
+  const plain = text.split("\n\n")[0].replace(/\s+/g, " ").trim();
+  // A period that ends a sentence, not the one in "e.g." or "i.e.".
+  const end = plain.replace(/\b(e\.g|i\.e|etc|vs)\./g, (m) => m.replace(/\./g, "_")).search(/\.(\s|$)/);
+  return end > 0 ? plain.slice(0, end + 1) : plain;
+};
+
+/* ---- Tools ---- */
+
+const tools = [
+  {
+    name: "list_components",
+    description: `List the components of ${registry.name} with a one-line description each, optionally for one category.`,
+    inputSchema: {
+      type: "object",
+      properties: { category: { type: "string", description: "e.g. forms, overlays, navigation, data-display, feedback, layout, primitives, utilities" } },
+    },
+  },
+  {
+    name: "get_component",
+    description: "Full documentation of one component: import, description, every prop (type, default, description), subcomponents (like Tabs.List), and its Storybook examples.",
+    inputSchema: { type: "object", properties: { name: { type: "string", description: "Component name, e.g. Button, Tabs, or Tabs.List" } }, required: ["name"] },
+  },
+  {
+    name: "search_docs",
+    description: "Search components, props, hooks, utilities, and guides by keywords. Returns the best matches with a short excerpt.",
+    inputSchema: {
+      type: "object",
+      properties: { query: { type: "string" }, limit: { type: "number", description: "Max results (default 8)" } },
+      required: ["query"],
+    },
+  },
+  {
+    name: "get_guide",
+    description: "Read a guide: setup (install and stylesheet), usage, theming (brands, accent, dark mode), languages (LocaleProvider, RTL), validation (useFormValidation).",
+    inputSchema: { type: "object", properties: { topic: { type: "string", enum: registry.guides.map((g) => g.id) } }, required: ["topic"] },
+  },
+];
+
+function findComponent(name) {
+  const wanted = name.trim().toLowerCase();
+  for (const c of registry.components) {
+    if (c.name.toLowerCase() === wanted) return { component: c };
+    const sub = (c.subcomponents ?? []).find((s) => s.name.toLowerCase() === wanted);
+    if (sub) return { component: c, sub };
+  }
+  return undefined;
+}
+
+function search(query, limit = 8) {
+  const terms = query.toLowerCase().split(/\W+/).filter((t) => t.length > 1);
+  const docs = [
+    ...registry.components.map((c) => ({
+      kind: "component",
+      name: c.name,
+      title: c.name,
+      text: [c.description, ...c.props.map((p) => `${p.name} ${p.description}`), ...(c.subcomponents ?? []).map((s) => `${s.name} ${s.description}`)].join(" "),
+      summary: firstSentence(c.description),
+    })),
+    ...registry.hooks.map((h) => ({ kind: "hook", name: h.name, title: h.name, text: `${h.signature} ${h.description}`, summary: firstSentence(h.description) })),
+    ...registry.utilities.map((u) => ({ kind: "utility", name: u.name, title: u.name, text: `${u.signature} ${u.description}`, summary: firstSentence(u.description) })),
+    ...registry.guides.map((g) => ({ kind: "guide", name: g.id, title: `Guide: ${g.title}`, text: g.markdown, summary: firstSentence(g.markdown.replace(/^[#>].*$/gm, "")) })),
+  ];
+  const scored = docs
+    .map((d) => {
+      const title = d.title.toLowerCase();
+      const text = d.text.toLowerCase();
+      let score = 0;
+      for (const t of terms) {
+        if (title === t) score += 20;
+        else if (title.includes(t)) score += 8;
+        const hits = text.split(t).length - 1;
+        score += Math.min(hits, 5);
+      }
+      return { ...d, score };
+    })
+    .filter((d) => d.score > 0)
+    .sort((a, b) => b.score - a.score)
+    .slice(0, limit);
+  if (!scored.length) return `No matches for "${query}". Try list_components or a broader term.`;
+  return scored
+    .map((d) => `- [${d.kind}] ${d.title}: ${d.summary || "(no description)"}${d.kind === "component" ? " (get_component for props)" : d.kind === "guide" ? ` (get_guide topic "${d.name}")` : ""}`)
+    .join("\n");
+}
+
+function callTool(name, args = {}) {
+  switch (name) {
+    case "list_components": {
+      const list = registry.components.filter((c) => !args.category || c.category === String(args.category).toLowerCase());
+      if (!list.length) return { text: `No components in "${args.category}". Categories: ${[...new Set(registry.components.map((c) => c.category))].join(", ")}.`, isError: true };
+      return {
+        text: [
+          `${registry.name} ${registry.version}: ${list.length} components. Import from the package root; import the stylesheet once (${registry.stylesheet}).`,
+          "",
+          ...list.map((c) => `- ${c.name} (${c.category})${c.subcomponents?.length ? ` [${c.subcomponents.map((s) => s.name).join(", ")}]` : ""}: ${firstSentence(c.description)}`),
+        ].join("\n"),
+      };
+    }
+    case "get_component": {
+      const found = findComponent(String(args.name ?? ""));
+      if (!found) return { text: `No component "${args.name}". Use list_components or search_docs.`, isError: true };
+      if (found.sub) {
+        const s = found.sub;
+        return {
+          text: [`# ${s.name}`, "", `Part of ${found.component.name}: ${found.component.import}`, "", s.description, "", "## Props", "", ...s.props.map(propLine)]
+            .filter((l) => l !== undefined)
+            .join("\n"),
+        };
+      }
+      return { text: componentDoc(found.component) };
+    }
+    case "search_docs":
+      return { text: search(String(args.query ?? ""), Number(args.limit) || 8) };
+    case "get_guide": {
+      const guide = registry.guides.find((g) => g.id === args.topic);
+      if (!guide) return { text: `Guides: ${registry.guides.map((g) => g.id).join(", ")}.`, isError: true };
+      return { text: `# ${guide.title}\n\n${guide.markdown}` };
+    }
+    default:
+      return undefined;
+  }
+}
+
+/* ---- JSON-RPC over stdio ---- */
+
+const send = (message) => process.stdout.write(`${JSON.stringify(message)}\n`);
+const reply = (id, result) => send({ jsonrpc: "2.0", id, result });
+const fail = (id, code, message) => send({ jsonrpc: "2.0", id, error: { code, message } });
+
+function handle(message) {
+  const { id, method, params } = message;
+  const isRequest = id !== undefined && id !== null;
+  switch (method) {
+    case "initialize":
+      return reply(id, {
+        protocolVersion: params?.protocolVersion ?? "2025-06-18",
+        capabilities: { tools: {} },
+        serverInfo: { name: `${registry.name} docs`, version: registry.version },
+        instructions: `Documentation for the ${registry.name} React component library. Start with list_components or search_docs, then get_component for exact props.`,
+      });
+    case "ping":
+      return isRequest && reply(id, {});
+    case "tools/list":
+      return reply(id, { tools });
+    case "tools/call": {
+      const result = callTool(params?.name, params?.arguments);
+      if (!result) return fail(id, -32602, `Unknown tool: ${params?.name}`);
+      return reply(id, { content: [{ type: "text", text: result.text }], isError: Boolean(result.isError) });
+    }
+    default:
+      // Notifications (no id) need no answer.
+      if (isRequest) fail(id, -32601, `Method not found: ${method}`);
+  }
+}
+
+createInterface({ input: process.stdin }).on("line", (line) => {
+  if (!line.trim()) return;
+  let message;
+  try {
+    message = JSON.parse(line);
+  } catch {
+    return send({ jsonrpc: "2.0", id: null, error: { code: -32700, message: "Parse error" } });
+  }
+  try {
+    handle(message);
+  } catch (error) {
+    if (message.id !== undefined) fail(message.id, -32603, String(error?.message ?? error));
+  }
+});