@viasat/beam-react-claude-plugin 2.43.2 → 2.45.0

package/.claude-plugin/plugin.json

@@ -3,7 +3,7 @@
   "name": "beam-react-claude-plugin",
   "displayName": "Beam React Claude Plugin",
   "description": "Equips AI tools with Beam Design System context for building, auditing, and answering implementation questions across tokens, components and data sources in React.",
-  "version": "2.43.2",
+  "version": "2.45.0",
   "author": {
     "name": "Viasat",
     "url": "https://git.viasat.com/vega/beam"
@@ -15,7 +15,7 @@
       "command": "npx",
       "args": [
         "-y",
-        "@viasat/beam-react-mcp@2.43.2"
+        "@viasat/beam-react-mcp@2.45.0"
       ]
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@viasat/beam-react-claude-plugin",
-  "version": "2.43.2",
+  "version": "2.45.0",
   "description": "Claude Code plugin that reduces AI hallucinations on Beam usage. Ships skills, reference docs, and a user-invocable token audit command.",
   "license": "MIT",
   "author": "Viasat",

package/references/data-sources.md

@@ -17,6 +17,26 @@ The `@viasat/beam-react-mcp` server provides structured, offline access to Beam
 
 Data comes from `beam-manifest.json`, bundled in the npm package. Zero network calls at runtime.
 
+### Paired hooks and context-driven components
+
+Some components are driven by an imperative hook or context provider, not by props and children alone. `ToastContainer` is controlled by `useToast()`, not by passing toasts as JSX. For these, `getComponent` returns a `pairedHooks` array. Each entry has the hook or provider `name`, `kind`, full `signature` (params plus resolved return type), and `importPath`.
+
+Before implementing any component that manages state across a tree (Toast, Dialog, Popover, Select, Menu, Stepper, SideNav), follow these steps in order:
+
+1. Call `getComponent` and inspect `pairedHooks`.
+2. If `pairedHooks` is present, read every entry's signature before writing code. The hook is the API, and props alone will produce broken usage. If the component also lists subcomponents (for example Menu with `Menu.Trigger`), use both. The hook drives state and the subcomponents build the tree.
+3. If `pairedHooks` is absent and `getComponent` lists subcomponents (for example `Dialog.Trigger`, `Select.Option`), the subcomponents are the API. Build with those. Do not grep.
+4. If `pairedHooks` is absent and there are no subcomponents, only then grep the installed package for sibling hook or provider exports. The package ships compiled `.d.ts` files (`export declare const …`) and re-export barrels (`export * from …`, `export { useX } from …`), so the pattern must match all three forms. Folder names do not match component names (e.g. `ToastContainer` lives under `lib/Toasts/`), so grep the whole `lib/` tree:
+
+```bash
+grep -rEn "export (declare )?(const|function) use[A-Z]|export (declare )?const [A-Z][A-Za-z]*Provider|export \{[^}]*(use[A-Z][A-Za-z]*|[A-Z][A-Za-z]*Provider)" \
+  node_modules/@viasat/beam-react/lib/
+```
+
+This is a backstop for one narrow case: a hook-driven component that shipped before it was added to the manifest's curated pairings. It is not a routine step, and most components will not reach it.
+
+Before using anything the grep finds, confirm it is public API — i.e. it resolves through the package barrel. The root `node_modules/@viasat/beam-react/index.d.ts` only re-exports wildcards (`export * from './lib'`), so a name won't appear there literally; instead confirm it is re-exported from its own component barrel, e.g. `grep -rn "useToast" node_modules/@viasat/beam-react/lib/Toasts/index.d.ts`. If a name is only in an implementation file and not re-exported from any `index.d.ts`, it is an internal detail (for example `useDialogContext`, `usePopoverContext`, `useSelectDropdown`), not public API. Do not use it.
+
 ## Fetching llms.txt (fallback) — use curl, not WebFetch
 
 When MCP is unavailable, fall back to llms.txt. **Use `curl` via Bash. Do NOT use the WebFetch tool.** WebFetch refuses to reproduce content verbatim and returns a summarized/categorized rewrite, which destroys the exact URLs, prop names, and descriptions you need. `curl` returns the raw markdown intact.

package/skills/beam-ui/SKILL.md

@@ -29,7 +29,7 @@ See `references/data-sources.md` § MCP server for the tool catalog and call ord
 ## Checklist (each → a TodoWrite todo)
 
 1. **Plan.** BUILD: component tree, composition rule, expected tokens. ASK: list components/concepts to look up (cap ~5).
-2. **Gather.** Try MCP first: `listComponents` to discover, `getComponent` for props/story index, `getComponentStory` for usage examples. If MCP unavailable, tell the user: "The Beam MCP server is unavailable — falling back to llms.txt. If you weren't expecting this, please report it in **#beam-help**." Then fall back to curl llms.txt (index then specific pages). If llms.txt unreachable, fall back to node_modules `.d.ts` files. If all fail, apply the honesty rule — stop, don't fabricate.
+2. **Gather.** Try MCP first: `listComponents` to discover, `getComponent` for props/story index, `getComponentStory` for usage examples. For any component that manages state across a tree (Toast, Dialog, Popover, Select, Menu, Stepper, SideNav), check `getComponent`'s `pairedHooks` and read those hook/provider signatures before writing code, because the hook is the API and props alone produce broken usage. If `pairedHooks` is absent but the component lists subcomponents (like `Dialog.Trigger` or `Select.Option`), build with those subcomponents. Only grep node_modules for sibling `useX`/`Provider` exports when there are no `pairedHooks` and no subcomponents (see `references/data-sources.md` § Paired hooks). If MCP unavailable, tell the user: "The Beam MCP server is unavailable, falling back to llms.txt. If you weren't expecting this, please report it in **#beam-help**." Then fall back to curl llms.txt (index then specific pages). If llms.txt unreachable, fall back to node_modules `.d.ts` files. If all fail, apply the honesty rule: stop, don't fabricate.
 3. **Token check (BUILD).** Look up every color/dimension/font per `references/tokens.md`. Zero violations.
 4. **Produce.** BUILD: names/props/imports from Step 2's fetched data only; styling values are tokens (or `rem`). ASK: every claim cites its MCP or llms.txt source.
 5. **Self-check.** Names/props/imports match fetched data; zero token violations; composition matches the plan. If MCP and llms.txt were both unreachable, apply the honesty rule.
@@ -47,6 +47,7 @@ See `references/data-sources.md` § MCP server for the tool catalog and call ord
 | "MCP is running but curl is faster"             | MCP returns structured data with guaranteed parity. Don't skip it for raw text.                                  |
 | "Question, but they obviously want code"        | Default to ASK; end with the switch-to-BUILD prompt. Don't write files without an explicit BUILD request.        |
 | "node_modules has it, skip the fetch"           | MCP and llms.txt have descriptions/examples the `.d.ts` files lack. Try them first; node_modules is last resort. |
+| "ToastContainer takes toasts as children/props" | Context-driven components are driven by a hook. Check `pairedHooks` and read `useToast` before writing. Props-only is the canonical broken pattern. |
 
 ## Not in scope