@devalok/shilp-sutra 0.54.0 → 0.55.0

package/dist/ui/tree-view/index.d.ts

@@ -1,5 +1,4 @@
-"use client";
-export { TreeItem, type TreeItemProps } from './tree-item';
-export { TreeView, type TreeViewProps } from './tree-view';
-export { type TreeNode, useTree } from './use-tree';
+export { TreeItem, type TreeItemProps } from './tree-item.js';
+export { TreeView, type TreeViewProps } from './tree-view.js';
+export { type TreeNode, useTree } from './use-tree.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/ui/tree-view/tree-item.d.ts

@@ -1,5 +1,4 @@
-"use client";
-import { IconInput } from '../lib/icon-input';
+import { IconInput } from '../lib/icon-input.js';
 import * as React from 'react';
 export interface TreeItemProps {
     /** Unique identifier for this tree item */

package/dist/ui/tree-view/tree-view.d.ts

@@ -1,5 +1,4 @@
-"use client";
-import { TreeNode, useTree } from './use-tree';
+import { TreeNode, useTree } from './use-tree.js';
 import * as React from 'react';
 interface TreeContextValue {
     tree: ReturnType<typeof useTree>;

package/dist/ui/tree-view/use-tree.d.ts

@@ -1,5 +1,4 @@
-"use client";
-import { IconInput } from '../lib/icon-input';
+import { IconInput } from '../lib/icon-input.js';
 export interface TreeNode {
     id: string;
     label: string;

package/dist/ui/truncated-text.d.ts

@@ -1,4 +1,3 @@
-"use client";
 import * as React from 'react';
 type TruncateMode = 'end' | 'clamp' | 'middle';
 export interface TruncatedTextProps {

package/docs/recipes/install-astro.md

@@ -38,6 +38,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/docs/recipes/install-next-app-router.md

@@ -51,6 +51,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/docs/recipes/install-remix.md

@@ -34,6 +34,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/docs/recipes/install-tanstack-start.md

@@ -43,6 +43,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/docs/recipes/install-vite.md

@@ -49,6 +49,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/docs/recipes/troubleshoot.md

@@ -196,6 +196,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
@@ -204,6 +206,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.

package/llms.txt

@@ -1,6 +1,6 @@
 # @devalok/shilp-sutra
 
-> Radix UI + Tailwind 4 (CSS-first) + CVA design system for Devalok apps, v0.54.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).
 

package/mcp-manifest.json

@@ -2,7 +2,7 @@
   "$schema": "./mcp-manifest.schema.json",
   "manifestVersion": "1.2.0",
   "package": "@devalok/shilp-sutra",
-  "packageVersion": "0.54.0",
+  "packageVersion": "0.55.0",
   "components": {
     "accordion": {
       "displayName": "Accordion",
@@ -11697,6 +11697,10 @@
           "version": "0.32.0",
           "summary": "Initial release"
         }
+      ],
+      "peers": [
+        "@tiptap/pm",
+        "@tiptap/react"
       ]
     },
     "rich-text-editor": {
@@ -11857,6 +11861,10 @@
           "version": "0.1.1",
           "summary": "**Fixed** Added content sync effect so editor updates when `content` prop changes externally"
         }
+      ],
+      "peers": [
+        "@tiptap/pm",
+        "@tiptap/react"
       ]
     },
     "schedule-view": {

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@devalok/shilp-sutra",
-  "version": "0.54.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"
   },
@@ -735,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",
@@ -850,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",
@@ -879,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
     },
@@ -967,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.54.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/references/components.md

@@ -2,7 +2,7 @@
 
 # @devalok/shilp-sutra
 
-> Radix UI + Tailwind 4 (CSS-first) + CVA design system for Devalok apps, v0.54.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).
 

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.