@devalok/shilp-sutra 0.45.1 → 0.47.0

package/mcp-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./mcp-manifest.schema.json",
-  "manifestVersion": "1.0.0",
+  "manifestVersion": "1.1.0",
   "package": "@devalok/shilp-sutra",
-  "packageVersion": "0.45.1",
+  "packageVersion": "0.47.0",
   "components": {
     "accordion": {
       "displayName": "Accordion",
@@ -1780,6 +1780,17 @@
           "version": "0.1.0",
           "summary": "**Added** Initial release"
         }
+      ],
+      "peers": [
+        "d3-array",
+        "d3-axis",
+        "d3-format",
+        "d3-interpolate",
+        "d3-scale",
+        "d3-selection",
+        "d3-shape",
+        "d3-time-format",
+        "d3-transition"
       ]
     },
     "chat": {
@@ -2787,6 +2798,10 @@
           "version": "0.1.0",
           "summary": "**Added** Initial release"
         }
+      ],
+      "peers": [
+        "@tanstack/react-table",
+        "@tanstack/react-virtual"
       ]
     },
     "data-table-body": {
@@ -3001,6 +3016,10 @@
           "version": "0.1.0",
           "summary": "**Added** Initial release"
         }
+      ],
+      "peers": [
+        "@tanstack/react-table",
+        "@tanstack/react-virtual"
       ]
     },
     "devalok-grain": {
@@ -4038,6 +4057,9 @@
           "version": "0.1.0",
           "summary": "**Added** Initial release"
         }
+      ],
+      "peers": [
+        "input-otp"
       ]
     },
     "label": {
@@ -6370,6 +6392,95 @@
         }
       ]
     },
+    "surface": {
+      "displayName": "Surface",
+      "tier": "ui",
+      "import": "@devalok/shilp-sutra/ui/surface",
+      "serverSafe": true,
+      "description": "The low-level elevated container primitive. Owns background + shadow + radius + optional padding and border — nothing else. Card, Popover, Toast, Sheet, and other surfaces compose it.",
+      "props": {
+        "elevation": {
+          "type": {
+            "name": "enum",
+            "value": [
+              "flat",
+              "raised",
+              "floating",
+              "overlay"
+            ]
+          },
+          "required": false,
+          "defaultValue": "raised"
+        },
+        "padding": {
+          "type": {
+            "name": "enum",
+            "value": [
+              "none",
+              "sm",
+              "md",
+              "lg"
+            ]
+          },
+          "required": false,
+          "defaultValue": "none"
+        },
+        "radius": {
+          "type": {
+            "name": "enum",
+            "value": [
+              "none",
+              "control",
+              "surface",
+              "overlay",
+              "pill"
+            ]
+          },
+          "required": false,
+          "defaultValue": "surface"
+        },
+        "bordered": {
+          "type": {
+            "name": "enum",
+            "value": [
+              "true",
+              "false"
+            ]
+          },
+          "required": false,
+          "defaultValue": false
+        },
+        "asChild": {
+          "type": {
+            "name": "object",
+            "raw": "boolean — render as the passed child element (Radix Slot) instead of a div"
+          },
+          "required": false
+        }
+      },
+      "composition": {
+        "notes": [
+          "Server-safe — renders in RSC trees.",
+          "The base layer: `Card` = Surface + gap-model padding + color edge + header/content/footer slots. Reach for Card when you want that slot rhythm; reach for Surface for a plain elevated box.",
+          "`asChild` merges the surface classes onto your own element (a link, section, or `motion.div`) with no extra wrapper node.",
+          "Padding is symmetric all-side. For asymmetric or gap-model spacing, use Card or add your own utilities via `className`."
+        ]
+      },
+      "docPath": "docs/components/ui/surface.md",
+      "defaults": {
+        "elevation": "raised",
+        "padding": "none",
+        "radius": "surface",
+        "bordered": false
+      },
+      "examples": [
+        "// Raised panel with padding\n<Surface elevation=\"raised\" padding=\"md\">…</Surface>\n\n// On-page, border-led tile (no shadow)\n<Surface elevation=\"flat\" bordered padding=\"sm\">…</Surface>\n\n// The whole surface is a link\n<Surface asChild elevation=\"raised\" padding=\"sm\">\n  <a href=\"/upgrade\">Upgrade to Pro</a>\n</Surface>"
+      ],
+      "gotchas": [
+        "**Edge OR elevation, never both.** Combining `bordered` with a shadowed elevation (raised/floating/overlay) is the double-edge anti-pattern and dev-warns. Use `elevation=\"flat\"` with `bordered`, or drop `bordered` and let the shadow be the edge.",
+        "`flat` still uses `bg-surface-raised` (a card without a shadow), not the page background — it is a surface, not a hole."
+      ]
+    },
     "switch": {
       "displayName": "Switch",
       "tier": "ui",
@@ -8498,6 +8609,9 @@
           "version": "0.1.0",
           "summary": "**Added** Initial release"
         }
+      ],
+      "peers": [
+        "date-fns"
       ]
     },
     "deadline-indicator": {
@@ -8948,6 +9062,10 @@
         "All types have error fallback with download link",
         "Embed URLs auto-converted to embed format",
         "Audio player doesn't show separate Download button (integrated in card)"
+      ],
+      "peers": [
+        "react-pdf",
+        "react-zoom-pan-pinch"
       ]
     },
     "filter-bar": {
@@ -9398,6 +9516,10 @@
         "GFM (tables, strikethrough, task lists) is supported via `remark-gfm`",
         "Raw HTML is stripped by default — only enable `allowHtml` for trusted content",
         "Links open in a new tab by default (`target=\"_blank\"` with `rel=\"noopener noreferrer\"`)"
+      ],
+      "peers": [
+        "react-markdown",
+        "react-syntax-highlighter"
       ]
     },
     "master-detail": {
@@ -10103,6 +10225,11 @@
           "version": "0.32.0",
           "summary": "Initial release"
         }
+      ],
+      "peers": [
+        "@tiptap/react",
+        "@tiptap/starter-kit",
+        "@tiptap/extension-placeholder"
       ]
     },
     "rich-text-editor": {
@@ -10244,6 +10371,11 @@
           "version": "0.1.1",
           "summary": "**Fixed** Added content sync effect so editor updates when `content` prop changes externally"
         }
+      ],
+      "peers": [
+        "@tiptap/react",
+        "@tiptap/starter-kit",
+        "@tiptap/extension-placeholder"
       ]
     },
     "schedule-view": {
@@ -11924,7 +12056,7 @@
       },
       {
         "name": "--font-display",
-        "value": "\"Inter\", system-ui, sans-serif"
+        "value": "\"Manrope\", \"Inter\", system-ui, sans-serif"
       },
       {
         "name": "--font-body",

package/mcp-manifest.schema.json

@@ -81,6 +81,12 @@
           "items": { "type": "string" },
           "description": "Known-misuse bullets, verbatim, DO-NOT phrasing preferred."
         },
+        "peers": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Optional peer dependencies this component imports. Absent for core components (no extra install). Importing the component without these installed fails the build with 'Failed to resolve import'. Mirrors the recipe optional-peer table; read by the MCP preflight/verify_setup tools.",
+          "examples": [["@tanstack/react-table", "@tanstack/react-virtual"]]
+        },
         "changes": {
           "type": "array",
           "items": {

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@devalok/shilp-sutra",
-  "version": "0.45.1",
+  "version": "0.47.0",
   "description": "Devalok Design System — accessible React components, OKLCH design tokens, and Tailwind 4 CSS-first setup. Ships with AI-agent setup recipes.",
   "license": "MIT",
   "author": "Devalok Design & Strategy Studios <shilp-sutra@devalok.in>",
-  "homepage": "https://devalok-design.github.io/shilp-sutra/",
+  "homepage": "https://shilp-sutra.devalok.in",
   "repository": {
     "type": "git",
     "url": "https://github.com/devalok-design/shilp-sutra",
@@ -377,6 +377,11 @@
       "import": "./dist/ui/stepper.js",
       "default": "./dist/ui/stepper.js"
     },
+    "./ui/surface": {
+      "types": "./dist/ui/surface.d.ts",
+      "import": "./dist/ui/surface.js",
+      "default": "./dist/ui/surface.js"
+    },
     "./ui/switch": {
       "types": "./dist/ui/switch.d.ts",
       "import": "./dist/ui/switch.js",

package/scripts/welcome.mjs

@@ -173,7 +173,7 @@ function buildFullBanner(version, prevVersion) {
     lines.push(row(`     ${colour('+ docs/recipes/upgrading.md (safe-upgrade procedure)', DIM)}`))
   } else {
     lines.push(row(`   ${colour('✦', PINK)}  ${colour('@devalok/shilp-sutra', BOLD)}  ${version}`))
-    lines.push(row(`      ${colour('Tailwind 4 design system · 110+ components · RSC-safe', DIM)}`))
+    lines.push(row(`      ${colour('Tailwind 4 design system · 120+ components · RSC-safe', DIM)}`))
   }
   lines.push(colour(EMPTY, PINK_DIM))
   lines.push(row(`   ${colour('▸', PINK)} Setup recipe (pick your framework):`))
@@ -183,7 +183,9 @@ function buildFullBanner(version, prevVersion) {
   lines.push(row(`     ${colour('https://shilp-sutra.devalok.in/themer', DIM)}`))
   lines.push(colour(EMPTY, PINK_DIM))
   lines.push(row(`   ${colour('▸', PINK)} Wire your AI agent (Claude Code / Cursor / Codex):`))
-  lines.push(row(`     ${colour('cp -r node_modules/@devalok/shilp-sutra/skill \\', DIM)}`))
+  lines.push(row(`     ${colour('connect the live docs MCP → https://shilp-sutra.devalok.in/mcp', DIM)}`))
+  lines.push(row(`     ${colour('(version-exact setup + peer preflight; beats guessing)', DIM)}`))
+  lines.push(row(`     ${colour('or copy the skill: cp -r node_modules/@devalok/shilp-sutra/skill \\', DIM)}`))
   lines.push(row(`        ${colour('~/.claude/skills/shilp-sutra', DIM)}`))
   lines.push(colour(EMPTY, PINK_DIM))
   lines.push(row(`   ${colour('Disable this banner: SHILP_SUTRA_NO_WELCOME=1', DIM)}`))

package/skill/SKILL.md

@@ -3,7 +3,7 @@ name: shilp-sutra
 description: Add, configure, and use components from Devalok's shilp-sutra design system (@devalok/shilp-sutra) — a Tailwind 4 + React 19 + CVA library with 110+ accessible components, OKLCH design tokens, framer-motion animations, and per-component RSC-safe entry points. Use this skill whenever the user mentions shilp-sutra, Devalok, the @devalok npm scope, or asks to install/add/style/theme UI in any React project that already depends on the package — even if they don't name it explicitly. Use it instead of generic shadcn/ui, MUI, or Chakra knowledge when shilp-sutra is in the project. Covers Next.js (App + Pages), Vite, Astro, Remix, TanStack Start setup playbooks; component API and variant reference; brand token customization; Server Component import patterns; and a troubleshoot tree for the thirteen most common breakages.
 license: MIT
 metadata:
-  version: "0.45.1"
+  version: "0.47.0"
   author: Devalok Design & Strategy Studios
   homepage: https://github.com/devalok-design/shilp-sutra
   npm: https://www.npmjs.com/package/@devalok/shilp-sutra

package/skill/references/components.md

@@ -2,7 +2,7 @@
 
 # @devalok/shilp-sutra
 
-> Radix UI + Tailwind 4 (CSS-first) + CVA design system for Devalok apps, v0.45.1.
+> Radix UI + Tailwind 4 (CSS-first) + CVA design system for Devalok apps, v0.47.0.
 > Built on the same primitives as shadcn/ui but with DIFFERENT prop APIs — never guess from shadcn knowledge; verify every prop.
 > This file is a ROUTER: it tells you what exists and where to get details. Do not look for prop tables here — fetch them per component (MCP tool or per-component doc file below).
 
@@ -102,6 +102,7 @@ Format: `[name](doc path): summary`. Import paths follow `@devalok/shilp-sutra/<
 - [stat-flash](docs/components/ui/stat-flash.md)
 - [status-dot](docs/components/ui/status-dot.md)
 - [stepper](docs/components/ui/stepper.md)
+- [surface](docs/components/ui/surface.md): The low-level elevated container primitive
 - [switch](docs/components/ui/switch.md)
 - [table](docs/components/ui/table.md)
 - [table-row-link](docs/components/ui/table-row-link.md)

package/skill/references/setup-tanstack-start.md

@@ -2,21 +2,30 @@
 
 # Install: TanStack Start
 
-> Setup recipe for adding `@devalok/shilp-sutra` to a TanStack Start project (the React full-stack framework built on Vinxi/Vite).
+> Setup recipe for adding `@devalok/shilp-sutra` to a TanStack Start project (the React full-stack framework built on Vite).
+
+> **Updated 2026-07-10 for the Vite-plugin era.** TanStack Start moved off Vinxi: the package is now `@tanstack/react-start` (not `@tanstack/start`), config lives in `vite.config.ts` (not `app.config.ts`), and the app root is `src/` (not `app/`). If you are on an old Vinxi-based project (`app.config.ts`, `@tanstack/start`), migrate to the Vite plugin first — see the TanStack Start docs.
 
 ## 1. Detect
 
 You are in this recipe if:
 
-- `package.json` lists `"@tanstack/start"` and `"@tanstack/react-router"`
-- `app.config.{ts,js}` (Vinxi) exists at the project root
-- `app/router.tsx` and `app/routes/__root.tsx` exist
+- `package.json` lists `"@tanstack/react-start"` and `"@tanstack/react-router"`
+- `vite.config.{ts,js}` exists and uses the `tanstackStart` plugin from `@tanstack/react-start/plugin/vite`
+- `src/router.tsx` and `src/routes/__root.tsx` exist (a `src/routeTree.gen.ts` is generated on first run)
+
+If instead you see `app.config.ts` + `@tanstack/start`, that is the legacy Vinxi setup — this recipe does not apply until you migrate.
 
 ## 2. Install
 
 ```bash
+# pnpm
 pnpm add @devalok/shilp-sutra framer-motion
 pnpm add -D tailwindcss@^4 @tailwindcss/vite
+
+# npm
+npm install @devalok/shilp-sutra framer-motion
+npm install -D tailwindcss@^4 @tailwindcss/vite
 ```
 
 Optional:
@@ -40,39 +49,79 @@ Some components ship hard peers as optional. **Install BEFORE first import** or
 | `@devalok/shilp-sutra/composed/markdown-viewer`            | `pnpm add react-markdown react-syntax-highlighter`                                                      |
 | Any `Icon` / `IconButton` with Tabler icons                | `pnpm add @tabler/icons-react`                                                                          |
 
-## 3. Wire Tailwind 4 in `app.config.ts`
+## 3. Wire Tailwind 4 in `vite.config.ts`
+
+Add `@tailwindcss/vite` to the existing plugins array. `tanstackStart()` must come before `viteReact()`; `tailwindcss()` can go first so tokens are processed early.
 
 ```ts
-import { defineConfig } from "@tanstack/start/config";
+import { defineConfig } from "vite";
+import { tanstackStart } from "@tanstack/react-start/plugin/vite";
+import viteReact from "@vitejs/plugin-react";
 import tailwindcss from "@tailwindcss/vite";
 
 export default defineConfig({
-  vite: {
-    plugins: [tailwindcss()],
-  },
+  plugins: [
+    tailwindcss(),
+    tanstackStart(),
+    viteReact(),
+  ],
 });
 ```
 
+Do **not** add a `tailwind.config.{ts,js}` — Tailwind 4 is CSS-first.
+
 ## 4. Wire tokens
 
-Create `app/styles/globals.css`:
+Create `src/styles/globals.css`:
 
 ```css
 @import "tailwindcss";
 @import "@devalok/shilp-sutra/css";
 ```
 
-Import it from `app/routes/__root.tsx`:
+Wire it as an asset-URL stylesheet from the root route's `head` (the TanStack Start idiom — the `?url` suffix emits the file as an asset instead of inlining it):
 
 ```tsx
-import "../styles/globals.css";
-```
+// src/routes/__root.tsx
+import {
+  createRootRoute,
+  HeadContent,
+  Outlet,
+  Scripts,
+} from "@tanstack/react-router";
+import globalsCss from "../styles/globals.css?url";
 
-If you prefer asset-URL imports the way Remix does it, use `import css from "../styles/globals.css?url"` and add `<link rel="stylesheet" href={css} />` to the `<head>` returned by `__root.tsx`.
+export const Route = createRootRoute({
+  head: () => ({
+    meta: [
+      { charSet: "utf-8" },
+      { name: "viewport", content: "width=device-width, initial-scale=1" },
+    ],
+    links: [{ rel: "stylesheet", href: globalsCss }],
+  }),
+  component: RootComponent,
+});
+
+function RootComponent() {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <head>
+        <HeadContent />
+      </head>
+      <body>
+        <Outlet />
+        <Scripts />
+      </body>
+    </html>
+  );
+}
+```
 
 ## 5. Theme toggle
 
-Create `public/theme-bootstrap.js` (a static asset served verbatim):
+Add a pre-hydration bootstrap so there is no flash of the wrong theme. The cleanest place is a `scripts` entry on the root route (runs before hydration); a static `public/theme-bootstrap.js` referenced from `<head>` also works and is CSP-friendly.
+
+Static-asset approach — create `public/theme-bootstrap.js`:
 
 ```js
 (function () {
@@ -86,44 +135,36 @@ Create `public/theme-bootstrap.js` (a static asset served verbatim):
 })();
 ```
 
-Reference it from `app/routes/__root.tsx`:
+Reference it from the root route's `head` scripts:
 
 ```tsx
-import { createRootRoute, Outlet } from "@tanstack/react-router";
-
 export const Route = createRootRoute({
-  component: () => (
-    <html lang="en" suppressHydrationWarning>
-      <head>
-        <script src="/theme-bootstrap.js" />
-      </head>
-      <body>
-        <Outlet />
-      </body>
-    </html>
-  ),
+  head: () => ({
+    // ...meta, links as above...
+    scripts: [{ src: "/theme-bootstrap.js" }],
+  }),
+  component: RootComponent,
 });
 ```
 
-For runtime toggling, use the `useColorMode` hook — see [install-vite.md § 5](./install-vite.md#5-theme-toggle-no-next-themes-here).
+For runtime toggling inside components, use the `useColorMode` hook — see [install-vite.md § 5](./install-vite.md#5-theme-toggle-no-next-themes-here).
 
 ## 6. Toaster (optional)
 
-Mount in `__root.tsx` next to `<Outlet />`:
+Mount once in `__root.tsx`'s `RootComponent`, next to `<Outlet />`:
 
 ```tsx
 import { Toaster } from "@devalok/shilp-sutra/ui/toaster";
 
 // inside <body>
-<>
-  <Outlet />
-  <Toaster />
-</>
+<Outlet />
+<Toaster />
+<Scripts />
 ```
 
 ## 7. Verify
 
-Create or replace `app/routes/index.tsx`:
+Create or replace `src/routes/index.tsx`:
 
 ```tsx
 import { createFileRoute } from "@tanstack/react-router";
@@ -132,7 +173,11 @@ import { Stack } from "@devalok/shilp-sutra/ui/stack";
 import { Text } from "@devalok/shilp-sutra/ui/text";
 
 export const Route = createFileRoute("/")({
-  component: () => (
+  component: Home,
+});
+
+function Home() {
+  return (
     <Stack className="p-ds-08" gap="ds-04">
       <Text variant="heading-2xl">Hello, Shilp Sutra</Text>
       <Stack direction="row" gap="ds-03">
@@ -140,21 +185,23 @@ export const Route = createFileRoute("/")({
         <Button variant="soft">Soft</Button>
       </Stack>
     </Stack>
-  ),
-});
+  );
+}
 ```
 
-Run `pnpm dev` and open the URL.
+Run `pnpm dev` and open the printed URL. Expected output matches [Next App Router § 7](./install-next-app-router.md#7-verify-the-install).
 
 ## 8. TanStack Start specifics
 
+- **No `transpilePackages` equivalent — and you do not need one.** TanStack Start's Vite resolves `@devalok/shilp-sutra` from `node_modules` as native ESM.
 - **Server functions** (`createServerFn`) — do not import shilp-sutra components inside server functions; they run server-only.
-- **Streaming SSR** is the default. All shilp-sutra components SSR cleanly because they have no client-only side effects at module top-level.
+- **Streaming SSR** is the default. Shilp Sutra components SSR cleanly (no client-only side effects at module top-level).
 - **`framer-motion` SSR** — animations gracefully degrade on the initial render.
-- **CSP.** The static `theme-bootstrap.js` asset complies with strict CSP (no inline scripts required).
+- **`routeTree.gen.ts` is generated** — do not edit it by hand; it regenerates on dev/build.
 
 ## 9. What NOT to do
 
-- ❌ Add `tailwind.config.{ts,js}` — Tailwind 4 is CSS-first.
-- ❌ Mount `<Toaster />` inside route components — it should live once at the `__root`.
-- ❌ Mix `@tailwindcss/postcss` and `@tailwindcss/vite` — pick one (Vite plugin recommended for TanStack Start).
+- ❌ Add a `tailwind.config.{ts,js}` — Tailwind 4 is CSS-first.
+- ❌ Use `@tanstack/start` / `app.config.ts` / `@tanstack/start/config` — that is the retired Vinxi setup. Current TanStack Start is `@tanstack/react-start` + `vite.config.ts`.
+- ❌ Mount `<Toaster />` inside route components — it lives once at the `__root`.
+- ❌ Mix `@tailwindcss/postcss` and `@tailwindcss/vite` — pick the Vite plugin.