@devalok/shilp-sutra 0.47.0 → 0.49.0

package/AGENTS.md

@@ -20,24 +20,13 @@ If you are a human, read [README.md](./README.md) instead.
 
 ## How to get details, in priority order
 
-1. **shilp-sutra MCP** — version-exact answers as JSON, cheapest on context. Hosted at `https://shilp-sutra.devalok.in/mcp` (connect it if it isn't already; it beats reading the frozen docs in `node_modules`). Reference tools: `find_component(query)`, `get_component(name, sections?)`, `get_tokens(category)`, `get_setup(framework)`, `upgrade(from, to)`, `search_docs(query)`. Setup tools: `detect_framework(packageJson)`, `preflight(framework, imports)`, `validate_snippet(code)`, `verify_setup(...)`, `report_issue(...)`. Always pass the consumer's installed version (from `node_modules/@devalok/shilp-sutra/package.json`) as `version`.
+1. **shilp-sutra MCP** — version-exact answers as JSON, cheapest on context. Hosted at `https://shilp-sutra.devalok.in/mcp` (connect it if it isn't already; it beats reading the frozen docs in `node_modules`). The tool surface is listed under "MCP tools" below. Always pass the consumer's installed version (from `node_modules/@devalok/shilp-sutra/package.json`) as `version`.
 2. **`packages/core/llms.txt`** — the ~3K-token router: what exists + where to get detail. Load this by default; it is deliberately tiny.
 3. **`packages/core/docs/components/<tier>/<name>.md`** — single-component doc (~3K tokens: props, examples, composability, gotchas). Read ONLY the components you're using — never bulk-read the directory or concatenate these.
 4. **`packages/core/mcp-manifest.json`** — everything machine-readable (props, tokens, composition; react-docgen shape). Prefer targeted reads over prose when you need structured data without the MCP.
 5. **`packages/core/docs/recipes/<framework>.md`** — copy-paste install + setup for the user's framework.
 6. **`packages/core/docs/recipes/upgrading.md`** + **`MIGRATION.md`** — read BOTH before any version bump. See the hard constraint below.
 
-### Setting up in a new project (do this in order)
-
-If the MCP is connected, run the setup sequence instead of guessing — it closes the four traps that break agent-driven installs (peer-dep cliffs, silent TW4 dead classes, wrong recipe, mis-wired CSS/config):
-
-1. `detect_framework(packageJson)` → the right recipe id + package manager (don't assume App Router, or that `create-remix` still makes Remix).
-2. `get_setup(recipe)` → the full, version-live recipe. Follow every step.
-3. `preflight(framework, imports)` → the exact install for the OPTIONAL peer deps your imports need. Run BEFORE first import or the build fails with `Failed to resolve import`.
-4. `validate_snippet(code)` → run on each file BEFORE writing it. Catches bare `shadow`, `-surface-N`, `bg-gradient-to-*`, removed Button variants, invalid enum props — the dead classes fail silently (no error, no style).
-5. `verify_setup(globalsCss, nextConfig, imports, installedDeps)` → confirm CSS imports + order, `transpilePackages`, and peer coverage after wiring.
-
-Without the MCP, the same information is in `docs/recipes/` (per-framework §2a lists optional peers) and the `@devalok/eslint-plugin-shilp-sutra` plugin catches the dead classes at lint time.
 7. **`node_modules/@devalok/shilp-sutra/BREAKING.json`** — machine-readable manifest of every breaking change per version (moves, type narrowings, removals, renames). Read this programmatically when planning an upgrade — schema in `BREAKING.schema.json`. Lets you answer "does my code import any of these moved symbols?" without parsing CHANGELOG prose.
 
 (`llms-full.txt` and `llms-quick.txt` were removed in 0.45 — the router + per-component docs + manifest replaced them. Do not look for them.)
@@ -51,6 +40,41 @@ When the package is installed in a consumer project, the same files live at:
 
 Read these local files. Your training data is outdated and will hallucinate APIs that do not exist in the installed version.
 
+### MCP tools
+
+<!-- BEGIN:mcp-tools --><!-- generated by scripts/generate-tool-list.mjs — do not edit by hand -->
+_11 tools (source: `packages/mcp-server/src/index.mjs`):_
+
+**Reference:**
+- `find_component` — Search shilp-sutra components by keyword (authoritative component index).
+- `get_component` — Authoritative, version-exact reference for one component: props/variants/defaults as JSON, usage rules, examples, composition (compound parts,…
+- `get_setup` — Framework install recipe (vite, next-app-router, next-pages, remix, astro, tanstack-start) or guides (customize-brand, server-components, troubleshoot,…
+- `get_tokens` — Design-token reference (color, spacing, typography, radius, shadow, motion, z) as JSON.
+- `search_docs` — Full-text search across component docs and recipes for patterns and guidance the other tools don't slice (e.g. "focus ring", "dark mode toggle").
+- `upgrade` — Structured breaking changes + migration pointers between two shilp-sutra versions.
+
+**Setup:**
+- `detect_framework` — Given the consumer app's package.json, returns the correct setup recipe id + package manager, so you never guess (or follow a recipe for the wrong framework).
+- `preflight` — Before writing setup code: given a framework and the component subpaths you intend to import, returns the exact install command for the optional PEER…
+- `validate_snippet` — Pre-write linter.
+- `verify_setup` — Post-install gate.
+
+**Write:**
+- `report_issue` — File a bug report, feature request, suggestion, or docs-gap on the shilp-sutra repo when you hit a wall using the design system.
+<!-- END:mcp-tools -->
+
+### Setting up in a new project (do this in order)
+
+If the MCP is connected, run the setup sequence instead of guessing — it closes the four traps that break agent-driven installs (peer-dep cliffs, silent TW4 dead classes, wrong recipe, mis-wired CSS/config):
+
+1. `detect_framework(packageJson)` → the right recipe id + package manager (don't assume App Router, or that `create-remix` still makes Remix).
+2. `get_setup(recipe)` → the full, version-live recipe. Follow every step.
+3. `preflight(framework, imports)` → the exact install for the OPTIONAL peer deps your imports need. Run BEFORE first import or the build fails with `Failed to resolve import`.
+4. `validate_snippet(code)` → run on each file BEFORE writing it. Catches bare `shadow`, `-surface-N`, `bg-gradient-to-*`, removed Button variants, invalid enum props — the dead classes fail silently (no error, no style).
+5. `verify_setup(globalsCss, nextConfig, imports, installedDeps)` → confirm CSS imports + order, `transpilePackages`, and peer coverage after wiring.
+
+Without the MCP, the same information is in `docs/recipes/` (per-framework §2a lists optional peers) and the `@devalok/eslint-plugin-shilp-sutra` plugin catches the dead classes at lint time.
+
 ## Setup playbook (when adding shilp-sutra to a new project)
 
 If a user asks you to add shilp-sutra and the package is not yet installed:

package/BREAKING.json

@@ -243,6 +243,84 @@
         "New hosted MCP at https://shilp-sutra.devalok.in/mcp — six read-only tools, version param on every tool; upgrade(from,to) accepts pre-0.45 versions.",
         "New mcp-manifest.json ships at the package root (schema: mcp-manifest.schema.json)."
       ]
+    },
+    "0.48.0": {
+      "summary": "Emoji picker migrated from @emoji-mart/react to frimousse — native-only. Non-native art-style sets removed; a few emoji-extension exports removed/narrowed. Also: optional-peer accuracy fixes (recipes/manifest) and recipe corrections. Non-emoji component APIs unchanged.",
+      "migrationDoc": "MIGRATION.md#v0480--emoji-picker-migrated-to-frimousse-native-only",
+      "removed": [
+        {
+          "symbol": "emojiDataLoaders",
+          "where": "@devalok/shilp-sutra/composed/emoji-picker",
+          "replacement": "None — the emoji dataset is bundled and frimousse fetches its own. Delete usages."
+        }
+      ],
+      "narrowed": [
+        {
+          "prop": "EmojiNodeAttrs",
+          "components": [
+            "@devalok/shilp-sutra/composed/extensions/emoji-node"
+          ],
+          "from": "{ id, native, set, x, y }",
+          "to": "{ id, native }",
+          "fix": "Drop set/x/y — the node renders the native character."
+        },
+        {
+          "prop": "EmojiSuggestionItem",
+          "components": [
+            "@devalok/shilp-sutra/composed/extensions/emoji-suggestion"
+          ],
+          "from": "{ id, name, native, x, y }",
+          "to": "{ id, name, native }",
+          "fix": "Drop x/y — native-only, no spritesheet coordinates."
+        },
+        {
+          "prop": "createEmojiSuggestion(set) argument",
+          "components": [
+            "@devalok/shilp-sutra/composed/extensions/emoji-suggestion"
+          ],
+          "from": "createEmojiSuggestion(set?: string)",
+          "to": "createEmojiSuggestion()",
+          "fix": "Call with no argument."
+        }
+      ],
+      "notes": [
+        "Art-style emoji sets (apple/google/twitter/facebook) removed. set / theme / previewPosition / skinTonePosition (EmojiPicker) and emojiSet (RichChatInput/RichTextEditor) are now accepted-but-ignored no-ops; EmojiSet type retained for source compat. Everyone sees native platform emoji.",
+        "frimousse + @emoji-mart/data are now BUNDLED (lazy emoji chunk) — the emoji feature needs ZERO consumer peer installs and no --legacy-peer-deps on React 19 (the old @emoji-mart/react peer had no React-19 support).",
+        "New emojibaseUrl prop on EmojiPicker/EmojiPickerPopover to self-host the emoji dataset (removes the runtime jsdelivr CDN dependency for strict-CSP / offline apps).",
+        "Optional-peer accuracy: recipe §2a tables are now generated from source; added sonner / remark-gfm / date-fns / @tanstack/react-table (data-table-toolbar) rows and removed phantom @tiptap install instructions."
+      ]
+    },
+    "0.49.0": {
+      "summary": "Unified form-control validation state: one `state` prop (type FieldState) replaces the `error` boolean (Checkbox/Switch) and the `color` prop (Select). Radio/Combobox gain an explicit `state`. Also: Progress redesigned as a compound component (`showLabel`→`showValue`, color `default`→`accent`).",
+      "migrationDoc": "MIGRATION.md#v0490--unified-field-state",
+      "renamed": [
+        { "from": "error", "to": "state", "where": "Checkbox", "kind": "prop" },
+        { "from": "error", "to": "state", "where": "Switch", "kind": "prop" },
+        { "from": "color", "to": "state", "where": "SelectTrigger", "kind": "prop" },
+        { "from": "color", "to": "state", "where": "selectTriggerVariants", "kind": "variant" },
+        { "from": "showLabel", "to": "showValue", "where": "Progress", "kind": "prop" }
+      ],
+      "removed": [
+        {
+          "symbol": "statusBadgeVariants",
+          "where": "@devalok/shilp-sutra/composed/status-badge",
+          "replacement": "StatusBadge now composes <Badge variant=\"soft\"> + <Dot> and has no standalone CVA. Style via Badge/Dot props or className."
+        },
+        {
+          "symbol": "StatusDot",
+          "where": "@devalok/shilp-sutra/ui/status-dot",
+          "replacement": "Merged into <Dot>. Map: healthy → <Dot color=\"success\" pulse>, warning → <Dot color=\"warning\">, critical → <Dot color=\"error\">, neutral → <Dot color=\"neutral\">, inactive → <Dot color=\"neutral\" variant=\"off\">."
+        }
+      ],
+      "notes": [
+        "Checkbox/Switch `error` was a boolean; `state` is FieldState (\"default\" | \"error\" | \"warning\" | \"success\"). Replace `error` with `state=\"error\"` (there is no boolean form).",
+        "Select's `color` prop was validation-only and is gone; use `state`. The exported `selectTriggerVariants` CVA axis was likewise renamed `color` → `state`.",
+        "Additive (non-breaking) in the same release: Checkbox/Switch/Radio gain warning+success tints; Radio (RadioGroup) and Combobox gain an explicit `state` prop and now inherit FormField state; Select now inherits FormField state too (was manual-only); Combobox renders a validation border for the first time.",
+        "InputState and NumberInputState remain as @deprecated type aliases of FieldState — no type-import breakage. New canonical type FieldState is exported from @devalok/shilp-sutra/ui.",
+        "Progress redesigned as a compound component (Progress.Root/Track/Indicator/Segment/Label/Value). Smart `<Progress value/>` form still works. `showLabel` → `showValue`; the `color` neutral `\"default\"` → `\"accent\"` (type now \"accent\"|\"success\"|\"warning\"|\"error\"). Added label/max/segments/trackClassName. New parts exported from @devalok/shilp-sutra/ui.",
+        "ScheduleView: the ScheduleEvent `color` value \"primary\" was renamed \"accent\" (matches the DS colour vocabulary). Migrate { color: 'primary' } → { color: 'accent' }. It was the default, so untyped events are unaffected. Also added focus-visible rings on slot/event buttons.",
+        "New `Dot` primitive (@devalok/shilp-sutra/ui/dot) — the shared indicator dot. StatusBadge composes Badge + Dot; StatusDot and Badge's `dot` prop now render Dot internally. No API change to StatusBadge/StatusDot/Badge props (Badge's dot pulse animation shifted from a bespoke ripple to Dot's ping). StatusDot's `inactive` shade is now neutral-8 (was neutral-6)."
+      ]
     }
   }
 }