@devalok/shilp-sutra 0.53.0 → 0.55.0

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@devalok/shilp-sutra",
-  "version": "0.53.0",
+  "version": "0.55.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://shilp-sutra.devalok.in",
   "repository": {
     "type": "git",
-    "url": "https://github.com/devalok-design/shilp-sutra",
+    "url": "git+https://github.com/devalok-design/shilp-sutra.git",
     "directory": "packages/core"
   },
   "bugs": {
@@ -52,11 +52,8 @@
     "provenance": true
   },
   "dependencies": {
-    "@emoji-mart/data": "^1.2.1",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
-    "diff": "^9.0.0",
-    "frimousse": "^0.3.0",
     "tw-animate-css": "^1.4.0",
     "use-sync-external-store": "^1.6.0"
   },
@@ -710,11 +707,6 @@
       "import": "./dist/shell/notification-preferences.js",
       "default": "./dist/shell/notification-preferences.js"
     },
-    "./shell/sidebar": {
-      "types": "./dist/shell/sidebar.d.ts",
-      "import": "./dist/shell/sidebar.js",
-      "default": "./dist/shell/sidebar.js"
-    },
     "./shell/top-bar": {
       "types": "./dist/shell/top-bar.d.ts",
       "import": "./dist/shell/top-bar.js",
@@ -740,6 +732,16 @@
       "import": "./dist/hooks/use-mobile.js",
       "default": "./dist/hooks/use-mobile.js"
     },
+    "./hooks/use-touch-device": {
+      "types": "./dist/hooks/use-touch-device.d.ts",
+      "import": "./dist/hooks/use-touch-device.js",
+      "default": "./dist/hooks/use-touch-device.js"
+    },
+    "./hooks/use-viewport-height": {
+      "types": "./dist/hooks/use-viewport-height.d.ts",
+      "import": "./dist/hooks/use-viewport-height.js",
+      "default": "./dist/hooks/use-viewport-height.js"
+    },
     "./utils": {
       "types": "./dist/ui/lib/utils.d.ts",
       "import": "./dist/ui/lib/utils.js",
@@ -855,6 +857,10 @@
     "@tabler/icons-react": "^3.0.0",
     "@tanstack/react-table": "^8.0.0",
     "@tanstack/react-virtual": "^3.0.0",
+    "@tiptap/core": "^3.28.0",
+    "@tiptap/pm": "^3.28.0",
+    "@tiptap/react": "^3.28.0",
+    "@tiptap/suggestion": "^3.28.0",
     "d3-array": "^3.0.0",
     "d3-axis": "^3.0.0",
     "d3-format": "^3.0.0",
@@ -884,6 +890,18 @@
     "@tanstack/react-virtual": {
       "optional": true
     },
+    "@tiptap/core": {
+      "optional": true
+    },
+    "@tiptap/pm": {
+      "optional": true
+    },
+    "@tiptap/react": {
+      "optional": true
+    },
+    "@tiptap/suggestion": {
+      "optional": true
+    },
     "d3-array": {
       "optional": true
     },
@@ -972,8 +990,10 @@
     "d3-time-format": "^4.1.0",
     "d3-transition": "^3.0.1",
     "date-fns": "^4.4.0",
+    "diff": "^9.0.0",
     "esbuild": "^0.28.1",
     "framer-motion": "^12.42.2",
+    "frimousse": "^0.3.0",
     "input-otp": "^1.4.2",
     "prosemirror-state": "^1.4.4",
     "react-colorful": "^5.8.0",

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.53.0"
+  version: "0.55.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/chat-skill/README.md

@@ -0,0 +1,18 @@
+# shilp-sutra chat skill
+
+A small pointer that teaches AI chat assistants what `@devalok/shilp-sutra` is and
+routes them to the MCP server for the real, version-exact component docs. Use it on chat
+surfaces that have no native Agent Skills support. For coding agents (Claude Code,
+Cursor, Codex), use the full skill in the parent directory instead.
+
+All of these say the same thing; pick the file that matches where you are pasting.
+
+| Surface | File | How to load it |
+| --- | --- | --- |
+| claude.ai / Claude Desktop | `SKILL.md` | Add as a skill, or connect the MCP directly: `claude mcp add --transport http shilp-sutra https://shilp-sutra.devalok.in/mcp` |
+| ChatGPT (Custom GPT or Custom Instructions) | `chatgpt-instructions.md` | Paste the block into the GPT's Instructions field |
+| Gemini (Gem) | `gemini-instructions.md` | Paste the block into the Gem's Instructions field |
+| Copilot Chat / other | `SKILL.md` | Paste the body into the system or context prompt |
+
+The heavy lifting lives in the MCP server at https://shilp-sutra.devalok.in/mcp. These
+files only orient the model and point it there; they do not duplicate component docs.

package/skill/chat-skill/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: shilp-sutra
+description: >
+  Use whenever the user works with @devalok/shilp-sutra or the Devalok Design
+  System in a React or Next.js project: installing it, importing components,
+  building dashboards, theming with an archetype or a brand color, or fixing
+  token and setup issues. Trigger on any @devalok import or a component name
+  (Sidebar, StatCard, DataTable, DatePicker, TopBar, PageHeader) even when the
+  package is not named. Prefer this over shadcn/ui, Radix, MUI, or Chakra
+  knowledge whenever shilp-sutra is in the project.
+license: MIT
+metadata:
+  author: Devalok Design & Strategy Studio
+  homepage: https://github.com/devalok-design/shilp-sutra
+  npm: https://www.npmjs.com/package/@devalok/shilp-sutra
+---
+
+# shilp-sutra (Devalok Design System): chat quick reference
+
+`@devalok/shilp-sutra` is Devalok's design system for React and Next.js: Tailwind 4,
+React 19, CVA, OKLCH tokens. It is NOT shadcn/ui, Radix, MUI, or Chakra. The component
+APIs, token namespace, and setup all differ, so do not answer from memory of those
+libraries. This file is a pointer. The full, version-exact docs live in the shilp-sutra
+MCP server.
+
+## Install
+
+```bash
+pnpm add @devalok/shilp-sutra framer-motion
+```
+
+`framer-motion@^12` is a required peer. Add `sonner@^2` only if you render a `<Toaster />`.
+
+## Wire the CSS (Tailwind 4, no JS config)
+
+```css
+@import "tailwindcss";
+@import "@devalok/shilp-sutra/css";
+```
+
+There is no `tailwind.config.ts` and no preset. On Next.js, add
+`transpilePackages: ["@devalok/shilp-sutra"]` to `next.config`.
+
+## Import layers
+
+| Layer    | Import                                | Holds                                          |
+| -------- | ------------------------------------- | ---------------------------------------------- |
+| ui       | `@devalok/shilp-sutra/ui/<name>`      | primitives: Button, Input, Dialog, Select, ... |
+| composed | `@devalok/shilp-sutra/composed/<name>`| patterns: StatCard, DataTable, DatePicker, ... |
+| shell    | `@devalok/shilp-sutra/shell/<name>`   | app frame: TopBar, Sidebar, BottomNavbar       |
+
+Prefer per-component imports (`/ui/button`) over the barrel (`/ui`): smaller bundles and
+Server-Component safe.
+
+## Full docs live in the MCP: connect it
+
+For real component APIs, props, variants, tokens, and setup recipes, use the shilp-sutra
+MCP server. Do not guess prop or variant names; they are enumerated there.
+
+```
+https://shilp-sutra.devalok.in/mcp
+```
+
+Claude Code or Claude Desktop:
+
+```bash
+claude mcp add --transport http shilp-sutra https://shilp-sutra.devalok.in/mcp
+```
+
+Once connected, call `how_to_use` first, then `get_component`, `get_setup`, and
+`get_tokens` as needed.
+
+## Theming
+
+For a copy-paste theme (a 12-step accent ramp plus role tokens), send the user to the
+Themer: https://shilp-sutra.devalok.in/themer . Paste its CSS block after the
+`@import "@devalok/shilp-sutra/css";` line. Theming is CSS-only; there is no provider
+component.

package/skill/chat-skill/chatgpt-instructions.md

@@ -0,0 +1,26 @@
+<!-- Paste the block below into a ChatGPT Custom GPT's "Instructions" field, or into
+     Settings > Personalization > Custom Instructions. Keep it verbatim. -->
+
+You help users build UI with @devalok/shilp-sutra, the Devalok Design System for
+React and Next.js (Tailwind 4, React 19, CVA, OKLCH tokens).
+
+It is NOT shadcn/ui, Radix, MUI, or Chakra. The component APIs, token namespace, and
+setup differ from all of them. Do not answer from memory of those libraries, and do
+not invent prop or variant names.
+
+Setup:
+- Install: `pnpm add @devalok/shilp-sutra framer-motion` (framer-motion@^12 is a
+  required peer; add sonner@^2 only for a Toaster).
+- CSS (Tailwind 4, no JS config): `@import "tailwindcss";` then
+  `@import "@devalok/shilp-sutra/css";`. On Next.js add
+  `transpilePackages: ["@devalok/shilp-sutra"]`.
+- Import per component: `@devalok/shilp-sutra/ui/button`,
+  `@devalok/shilp-sutra/composed/stat-card`, `@devalok/shilp-sutra/shell/top-bar`.
+
+For real component APIs, props, variants, tokens, and setup recipes, tell the user to
+connect the shilp-sutra MCP server at https://shilp-sutra.devalok.in/mcp and to read
+its `how_to_use`, `get_component`, `get_setup`, and `get_tokens` tools. That server is
+the version-exact source of truth; this instruction block is only an orientation.
+
+For theming, point the user to the Themer at https://shilp-sutra.devalok.in/themer for
+a copy-paste CSS theme.

package/skill/chat-skill/gemini-instructions.md

@@ -0,0 +1,25 @@
+<!-- Paste the block below into a Gemini Gem's "Instructions" field. Keep it verbatim. -->
+
+Act as a helper for @devalok/shilp-sutra, the Devalok Design System for React and
+Next.js (Tailwind 4, React 19, CVA, OKLCH tokens).
+
+It is NOT shadcn/ui, Radix, MUI, or Chakra. Its component APIs, token namespace, and
+setup differ. Do not answer from memory of those libraries, and never invent prop or
+variant names.
+
+Setup:
+- Install: `pnpm add @devalok/shilp-sutra framer-motion` (framer-motion@^12 is a
+  required peer; add sonner@^2 only for a Toaster).
+- CSS (Tailwind 4, no JS config): `@import "tailwindcss";` then
+  `@import "@devalok/shilp-sutra/css";`. On Next.js add
+  `transpilePackages: ["@devalok/shilp-sutra"]`.
+- Import per component: `@devalok/shilp-sutra/ui/button`,
+  `@devalok/shilp-sutra/composed/stat-card`, `@devalok/shilp-sutra/shell/top-bar`.
+
+For real component APIs, props, variants, tokens, and setup recipes, direct the user to
+the shilp-sutra MCP server at https://shilp-sutra.devalok.in/mcp (tools: `how_to_use`,
+`get_component`, `get_setup`, `get_tokens`). It is the version-exact source of truth;
+these instructions are only an orientation.
+
+For theming, send the user to the Themer at https://shilp-sutra.devalok.in/themer for a
+copy-paste CSS theme.

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.53.0.
+> Radix UI + Tailwind 4 (CSS-first) + CVA design system for Devalok apps, v0.55.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).
 
@@ -94,6 +94,7 @@ Format: `[name](doc path): summary`. Import paths follow `@devalok/shilp-sutra/<
 - [select](docs/components/ui/select.md)
 - [separator](docs/components/ui/separator.md)
 - [sheet](docs/components/ui/sheet.md)
+- [sidebar](docs/components/ui/sidebar.md)
 - [skeleton](docs/components/ui/skeleton.md)
 - [slider](docs/components/ui/slider.md)
 - [spinner](docs/components/ui/spinner.md)
@@ -158,7 +159,6 @@ Format: `[name](doc path): summary`. Import paths follow `@devalok/shilp-sutra/<
 - [link-context](docs/components/shell/link-context.md): Exports: LinkProvider, useLink
 - [notification-center](docs/components/shell/notification-center.md)
 - [notification-preferences](docs/components/shell/notification-preferences.md)
-- [sidebar](docs/components/shell/sidebar.md)
 - [top-bar](docs/components/shell/top-bar.md)
 
 ### ai

package/skill/references/setup-astro.md

@@ -40,6 +40,8 @@ Some components ship hard peers as optional. **Install BEFORE first import.**
 | `@devalok/shilp-sutra/composed/date-picker` | `pnpm add date-fns` |
 | `@devalok/shilp-sutra/composed/file-preview` | `pnpm add react-pdf react-zoom-pan-pinch` |
 | `@devalok/shilp-sutra/composed/markdown-viewer` | `pnpm add react-markdown react-syntax-highlighter remark-gfm` |
+| `@devalok/shilp-sutra/composed/rich-chat-input` | `pnpm add -D @tiptap/pm @tiptap/react` *(types only — the runtime is bundled)* |
+| `@devalok/shilp-sutra/composed/rich-text-editor` | `pnpm add -D @tiptap/pm @tiptap/react` *(types only — the runtime is bundled)* |
 | `@devalok/shilp-sutra/composed/schedule-view` | `pnpm add date-fns` |
 | `@devalok/shilp-sutra/ui/charts` | `pnpm add d3-axis d3-scale d3-selection d3-shape` |
 | `@devalok/shilp-sutra/ui/data-table` | `pnpm add @tanstack/react-table @tanstack/react-virtual` |

package/skill/references/setup-next-app-router.md

@@ -53,6 +53,8 @@ Some components depend on third-party libraries that ship as optional peers. **I
 | `@devalok/shilp-sutra/composed/date-picker` | `pnpm add date-fns` |
 | `@devalok/shilp-sutra/composed/file-preview` | `pnpm add react-pdf react-zoom-pan-pinch` |
 | `@devalok/shilp-sutra/composed/markdown-viewer` | `pnpm add react-markdown react-syntax-highlighter remark-gfm` |
+| `@devalok/shilp-sutra/composed/rich-chat-input` | `pnpm add -D @tiptap/pm @tiptap/react` *(types only — the runtime is bundled)* |
+| `@devalok/shilp-sutra/composed/rich-text-editor` | `pnpm add -D @tiptap/pm @tiptap/react` *(types only — the runtime is bundled)* |
 | `@devalok/shilp-sutra/composed/schedule-view` | `pnpm add date-fns` |
 | `@devalok/shilp-sutra/ui/charts` | `pnpm add d3-axis d3-scale d3-selection d3-shape` |
 | `@devalok/shilp-sutra/ui/data-table` | `pnpm add @tanstack/react-table @tanstack/react-virtual` |

package/skill/references/setup-remix.md

@@ -36,6 +36,8 @@ Some components ship hard peers as optional. **Install BEFORE first import.**
 | `@devalok/shilp-sutra/composed/date-picker` | `pnpm add date-fns` |
 | `@devalok/shilp-sutra/composed/file-preview` | `pnpm add react-pdf react-zoom-pan-pinch` |
 | `@devalok/shilp-sutra/composed/markdown-viewer` | `pnpm add react-markdown react-syntax-highlighter remark-gfm` |
+| `@devalok/shilp-sutra/composed/rich-chat-input` | `pnpm add -D @tiptap/pm @tiptap/react` *(types only — the runtime is bundled)* |
+| `@devalok/shilp-sutra/composed/rich-text-editor` | `pnpm add -D @tiptap/pm @tiptap/react` *(types only — the runtime is bundled)* |
 | `@devalok/shilp-sutra/composed/schedule-view` | `pnpm add date-fns` |
 | `@devalok/shilp-sutra/ui/charts` | `pnpm add d3-axis d3-scale d3-selection d3-shape` |
 | `@devalok/shilp-sutra/ui/data-table` | `pnpm add @tanstack/react-table @tanstack/react-virtual` |

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

@@ -45,6 +45,8 @@ Some components ship hard peers as optional. **Install BEFORE first import.**
 | `@devalok/shilp-sutra/composed/date-picker` | `pnpm add date-fns` |
 | `@devalok/shilp-sutra/composed/file-preview` | `pnpm add react-pdf react-zoom-pan-pinch` |
 | `@devalok/shilp-sutra/composed/markdown-viewer` | `pnpm add react-markdown react-syntax-highlighter remark-gfm` |
+| `@devalok/shilp-sutra/composed/rich-chat-input` | `pnpm add -D @tiptap/pm @tiptap/react` *(types only — the runtime is bundled)* |
+| `@devalok/shilp-sutra/composed/rich-text-editor` | `pnpm add -D @tiptap/pm @tiptap/react` *(types only — the runtime is bundled)* |
 | `@devalok/shilp-sutra/composed/schedule-view` | `pnpm add date-fns` |
 | `@devalok/shilp-sutra/ui/charts` | `pnpm add d3-axis d3-scale d3-selection d3-shape` |
 | `@devalok/shilp-sutra/ui/data-table` | `pnpm add @tanstack/react-table @tanstack/react-virtual` |

package/skill/references/setup-vite.md

@@ -51,6 +51,8 @@ Some components ship hard peers as optional. **Install BEFORE first import.**
 | `@devalok/shilp-sutra/composed/date-picker` | `pnpm add date-fns` |
 | `@devalok/shilp-sutra/composed/file-preview` | `pnpm add react-pdf react-zoom-pan-pinch` |
 | `@devalok/shilp-sutra/composed/markdown-viewer` | `pnpm add react-markdown react-syntax-highlighter remark-gfm` |
+| `@devalok/shilp-sutra/composed/rich-chat-input` | `pnpm add -D @tiptap/pm @tiptap/react` *(types only — the runtime is bundled)* |
+| `@devalok/shilp-sutra/composed/rich-text-editor` | `pnpm add -D @tiptap/pm @tiptap/react` *(types only — the runtime is bundled)* |
 | `@devalok/shilp-sutra/composed/schedule-view` | `pnpm add date-fns` |
 | `@devalok/shilp-sutra/ui/charts` | `pnpm add d3-axis d3-scale d3-selection d3-shape` |
 | `@devalok/shilp-sutra/ui/data-table` | `pnpm add @tanstack/react-table @tanstack/react-virtual` |

package/skill/references/troubleshoot.md

@@ -198,6 +198,8 @@ In dev mode, calling `toast()` without a mounted `<Toaster />` logs a one-time c
 
 **Diagnosis:** Should not happen since v0.37.0 — `use-sync-external-store` was moved to runtime dependencies and is auto-installed transitively.
 
+**Why this dependency exists at all** (it is a hook built into React 18+, so it looks redundant): we do not use the shim ourselves. It is a TipTap transitive. TipTap's code is bundled into our `dist`, and that bundled chunk imports `use-sync-external-store/shim`. We externalize the shim rather than bundling it, because bundling forced a `createRequire` bridge into our Rollup runtime chunk that broke every Turbopack consumer. Externalized code must be resolvable from the consumer's tree, hence the declaration.
+
 If it still happens, install it explicitly:
 
 ```bash
@@ -206,6 +208,84 @@ pnpm add use-sync-external-store
 
 And open an issue at <https://github.com/devalok-design/shilp-sutra/issues> with the resolution graph (`pnpm why use-sync-external-store`) so we can fix the root cause.
 
+## Symptom: `Cannot find package 'sonner'` when you only imported a hook (or `'react-markdown'` from the AI barrel)
+
+**Diagnosis:** you imported a *barrel* rather than the component itself, and the barrel re-exports something with an optional peer.
+
+- `@devalok/shilp-sutra/hooks` re-exports `toast`, which needs `sonner`.
+- `@devalok/shilp-sutra/ai` re-exports the block renderer, which needs `react-markdown`.
+
+A bundler tree-shakes the unused branch away, so this is invisible in a client build. It bites at **runtime in Node** — SSR, a route handler, a test — where the import is evaluated for real.
+
+Fix — import the specific module instead of the barrel:
+
+```ts
+// needs sonner installed, because the barrel also exports toast
+import { useIsMobile } from '@devalok/shilp-sutra/hooks'
+
+// no optional peers at all
+import { useIsMobile } from '@devalok/shilp-sutra/hooks/use-mobile'
+```
+
+Every hook has its own subpath: `use-mobile`, `use-color-mode`, `use-touch-device`, `use-viewport-height`. Same rule applies across the library — a deep import never costs you more than that component needs.
+
+## Symptom: `error TS2305: Module '"react"' has no exported member 'ReactSVG'`
+
+**This is an upstream `@tabler/icons-react` bug, not a shilp-sutra one** — but you will hit it following our install instructions, so it is documented here.
+
+`@tabler/icons-react` (through 3.45.0, the current release) opens its type declarations with:
+
+```ts
+import { ReactSVG, … } from 'react'
+```
+
+React 18's types exported `ReactSVG`; React 19's removed it, keeping only `ReactSVGElement`. So on React 19 the icon package's own `.d.ts` fails to compile.
+
+You only see it with **all three**: React 19, `skipLibCheck: false`, and a direct `@tabler/icons-react` import in your own code. React 18 is unaffected, and the default `skipLibCheck: true` suppresses it.
+
+Workarounds, in order of preference:
+
+1. Leave `skipLibCheck: true` (the default in every framework scaffold). It suppresses errors inside dependency declarations — including this one.
+2. Import icons through our re-export instead of directly, so the broken declaration is never loaded into your program.
+3. Pin `@types/react` to 18 if your app is still on React 18.
+
+There is nothing to fix on our side: we neither wrap nor re-declare Tabler's types. Track it upstream at <https://github.com/tabler/tabler-icons/issues>.
+
+## Symptom: `error TS2307: Cannot find module '@devalok/shilp-sutra/ui/button'` under `"moduleResolution": "node"`
+
+**Diagnosis:** You are on TypeScript's legacy resolution mode, which predates and ignores the `exports` field in `package.json`. Our files live under `dist/`, and every public path is mapped through `exports` — legacy resolution looks for a literal `node_modules/@devalok/shilp-sutra/ui/button.js` and finds nothing.
+
+**Supported resolution modes:**
+
+| `moduleResolution` | Supported | Notes |
+|---|---|---|
+| `bundler` | ✅ | Recommended. Vite, Next.js, and most modern setups default to this. |
+| `node16` / `nodenext` | ✅ | Fully supported since 0.55.0. |
+| `node` (legacy) | ❌ | Cannot read `exports`. No subpath resolves. |
+
+Fix — in your `tsconfig.json`:
+
+```jsonc
+{ "compilerOptions": { "moduleResolution": "bundler" } }
+```
+
+## Symptom: `require('@devalok/shilp-sutra')` throws `ERR_REQUIRE_ESM`
+
+**Diagnosis:** The package is ESM-only — we ship no CommonJS build. Whether `require()` works depends on your Node version:
+
+| Node | `require('@devalok/shilp-sutra/ui/button')` |
+|---|---|
+| 22.12+ / 23+ | ✅ Works — `require(esm)` is supported and unflagged. Verified against every entry point, including the full `./ui` barrel. |
+| < 22.12 | ❌ `ERR_REQUIRE_ESM` |
+
+On older Node, use a dynamic import:
+
+```js
+const { Button } = await import('@devalok/shilp-sutra/ui/button')
+```
+
+Or move the consuming file to ESM (`"type": "module"`, or a `.mjs` extension). Every supported framework target — Next.js, Vite, Remix, Astro, TanStack Start — handles the ESM entry natively; this only affects hand-written CJS scripts.
+
 ## Symptom: Storybook MCP server `localhost:6006/mcp` returns 404
 
 **Diagnosis:** Storybook dev server isn't running, OR the MCP plugin is not enabled in this Storybook version.