@devalok/shilp-sutra 0.55.1 → 0.57.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devalok/shilp-sutra",
-  "version": "0.55.1",
+  "version": "0.57.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>",
@@ -54,8 +54,8 @@
   "dependencies": {
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
-    "tw-animate-css": "^1.4.0",
-    "use-sync-external-store": "^1.6.0"
+    "tailwind-merge": "^3.6.0",
+    "tw-animate-css": "^1.4.0"
   },
   "exports": {
     ".": {
@@ -688,6 +688,11 @@
       "import": "./dist/shell/app-command-palette.js",
       "default": "./dist/shell/app-command-palette.js"
     },
+    "./shell/app-shell": {
+      "types": "./dist/shell/app-shell.d.ts",
+      "import": "./dist/shell/app-shell.js",
+      "default": "./dist/shell/app-shell.js"
+    },
     "./shell/bottom-navbar": {
       "types": "./dist/shell/bottom-navbar.d.ts",
       "import": "./dist/shell/bottom-navbar.js",
@@ -836,7 +841,6 @@
     "fonts",
     "make-kit",
     "skill",
-    "scripts/welcome.mjs",
     "AGENTS.md",
     "BREAKING.json",
     "BREAKING.schema.json",
@@ -859,8 +863,16 @@
     "@tanstack/react-table": "^8.0.0",
     "@tanstack/react-virtual": "^3.0.0",
     "@tiptap/core": "^3.28.0",
+    "@tiptap/extension-highlight": "^3.28.0",
+    "@tiptap/extension-image": "^3.28.0",
+    "@tiptap/extension-list": "^3.28.0",
+    "@tiptap/extension-mention": "^3.28.0",
+    "@tiptap/extension-text-align": "^3.28.0",
+    "@tiptap/extensions": "^3.28.0",
+    "@tiptap/markdown": "^3.28.0",
     "@tiptap/pm": "^3.28.0",
     "@tiptap/react": "^3.28.0",
+    "@tiptap/starter-kit": "^3.28.0",
     "@tiptap/suggestion": "^3.28.0",
     "d3-array": "^3.0.0",
     "d3-axis": "^3.0.0",
@@ -894,12 +906,36 @@
     "@tiptap/core": {
       "optional": true
     },
+    "@tiptap/extension-highlight": {
+      "optional": true
+    },
+    "@tiptap/extension-image": {
+      "optional": true
+    },
+    "@tiptap/extension-list": {
+      "optional": true
+    },
+    "@tiptap/extension-mention": {
+      "optional": true
+    },
+    "@tiptap/extension-text-align": {
+      "optional": true
+    },
+    "@tiptap/extensions": {
+      "optional": true
+    },
+    "@tiptap/markdown": {
+      "optional": true
+    },
     "@tiptap/pm": {
       "optional": true
     },
     "@tiptap/react": {
       "optional": true
     },
+    "@tiptap/starter-kit": {
+      "optional": true
+    },
     "@tiptap/suggestion": {
       "optional": true
     },
@@ -960,7 +996,6 @@
   },
   "devDependencies": {
     "@emoji-mart/data": "^1.2.1",
-    "@emoji-mart/react": "^1.1.1",
     "@floating-ui/dom": "^1.8.0",
     "@floating-ui/react-dom": "^2.1.9",
     "@tabler/icons-react": "^3.45.0",
@@ -974,13 +1009,12 @@
     "@tiptap/extension-text-align": "^3.28.0",
     "@tiptap/extensions": "^3.28.0",
     "@tiptap/markdown": "^3.28.0",
+    "@tiptap/pm": "^3.28.0",
     "@tiptap/react": "^3.28.0",
     "@tiptap/starter-kit": "^3.28.0",
     "@tiptap/suggestion": "^3.28.0",
     "@types/react-syntax-highlighter": "^15.5.13",
     "aria-hidden": "^1.2.6",
-    "class-variance-authority": "^0.7.1",
-    "clsx": "^2.1.1",
     "d3-array": "^3.2.4",
     "d3-axis": "^3.0.0",
     "d3-format": "^3.1.2",
@@ -992,11 +1026,9 @@
     "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",
     "react-markdown": "^10.1.0",
     "react-pdf": "^10.4.1",
@@ -1004,8 +1036,7 @@
     "react-syntax-highlighter": "^16.1.1",
     "react-zoom-pan-pinch": "^4.0.3",
     "remark-gfm": "^4.0.1",
-    "sonner": "^2.0.7",
-    "tailwind-merge": "^3.6.0"
+    "sonner": "^2.0.7"
   },
   "scripts": {
     "build": "vite build && node scripts/post-build.mjs",
@@ -1018,7 +1049,6 @@
     "typecheck": "tsc --noEmit",
     "lint": "eslint src/",
     "test": "vitest run",
-    "test:coverage": "vitest run --coverage",
-    "postinstall": "node scripts/welcome.mjs || true"
+    "test:coverage": "vitest run --coverage"
   }
 }

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.55.1"
+  version: "0.57.0"
   author: Devalok Design & Strategy Studios
   homepage: https://github.com/devalok-design/shilp-sutra
   npm: https://www.npmjs.com/package/@devalok/shilp-sutra
@@ -77,15 +77,21 @@ The semantic surface names are the public API. The old numeric names (`surface-1
 | Token                          | Use for                                                                            |
 | ------------------------------ | ---------------------------------------------------------------------------------- |
 | `bg-surface-base`              | Page background                                                                    |
-| `bg-surface-raised`            | Cards, widgets, panels — anything that sits **on** the page                        |
-| `bg-surface-sunken`            | Shell chrome (Sidebar, TopBar), recessed regions                                   |
+| `bg-surface-panel`             | Cards, widgets, panels — anything that sits **on** the page                        |
+| `bg-surface-sunken`            | Wells and recessed regions                                                         |
 | `bg-surface-overlay`           | Dialog, Sheet, Popover, Toast, Combobox menus, any floating overlay                |
-| `bg-surface-raised-hover`      | Hover state on raised surfaces                                                     |
-| `bg-surface-raised-active`     | Active/pressed state on raised surfaces                                            |
+| `bg-surface-panel-hover`       | Hover state on panels                                                              |
+| `bg-surface-panel-active`      | Active/pressed state on panels                                                     |
 | `bg-surface-disabled`          | Disabled surfaces (paired with `text-surface-fg-disabled`)                         |
 | `bg-surface-inverted`          | Inverted surfaces (dark on light themes, light on dark themes)                     |
 
-Putting `bg-surface-base` on a card is a bug — cards belong on `surface-raised`. The pre-publish audit in the DS repo enforces this and blocks the old numeric aliases in component source files.
+Putting `bg-surface-base` on a card is a bug — cards belong on `surface-panel`. The pre-publish audit in the DS repo enforces this and blocks the old numeric aliases in component source files.
+
+**In LIGHT, `base`, `panel` and `overlay` are the same white.** That is deliberate: an edge makes a card a card, not a fill. So **never paint an interaction state with a container value** — `hover:bg-surface-panel` is invisible. Use `bg-surface-panel-hover` / `-panel-active`. This applies to JS conditionals too (`isSelected ? 'bg-surface-panel' : …`), which no lint rule can see.
+
+Borders come in two families: `surface-border-subtle` / `-border` / `-border-strong` are decorative and translucent; `surface-border-interactive` / `-interactive-strong` are solid control edges that carry WCAG 1.4.11. Form controls use the interactive pair.
+
+`surface-raised` was renamed `surface-panel` in 0.57.0 and `surface-chrome` was removed. Old names still resolve; run `pnpm eslint . --fix` to migrate.
 
 ## Adding a component
 

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.55.1.
+> Radix UI + Tailwind 4 (CSS-first) + CVA design system for Devalok apps, v0.57.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).
 
@@ -154,6 +154,7 @@ Format: `[name](doc path): summary`. Import paths follow `@devalok/shilp-sutra/<
 
 ### shell
 - [app-command-palette](docs/components/shell/app-command-palette.md)
+- [app-shell](docs/components/shell/app-shell.md)
 - [bottom-navbar](docs/components/shell/bottom-navbar.md)
 - [command-registry](docs/components/shell/command-registry.md): Exports: CommandRegistryProvider, useCommandRegistry
 - [link-context](docs/components/shell/link-context.md): Exports: LinkProvider, useLink

package/skill/references/setup-astro.md

@@ -40,8 +40,9 @@ 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/rich-chat-input` | `pnpm add @tiptap/core @tiptap/extension-highlight @tiptap/extension-image @tiptap/extension-list @tiptap/extension-mention @tiptap/extension-text-align @tiptap/extensions @tiptap/markdown @tiptap/pm @tiptap/react @tiptap/starter-kit @tiptap/suggestion date-fns` |
+| `@devalok/shilp-sutra/composed/diff` | `pnpm add react-syntax-highlighter` |
+| `@devalok/shilp-sutra/composed/rich-text-editor` | `pnpm add @tiptap/core @tiptap/extension-highlight @tiptap/extension-image @tiptap/extension-list @tiptap/extension-mention @tiptap/extension-text-align @tiptap/extensions @tiptap/markdown @tiptap/pm @tiptap/react @tiptap/starter-kit @tiptap/suggestion` |
 | `@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,8 +53,9 @@ 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/rich-chat-input` | `pnpm add @tiptap/core @tiptap/extension-highlight @tiptap/extension-image @tiptap/extension-list @tiptap/extension-mention @tiptap/extension-text-align @tiptap/extensions @tiptap/markdown @tiptap/pm @tiptap/react @tiptap/starter-kit @tiptap/suggestion date-fns` |
+| `@devalok/shilp-sutra/composed/diff` | `pnpm add react-syntax-highlighter` |
+| `@devalok/shilp-sutra/composed/rich-text-editor` | `pnpm add @tiptap/core @tiptap/extension-highlight @tiptap/extension-image @tiptap/extension-list @tiptap/extension-mention @tiptap/extension-text-align @tiptap/extensions @tiptap/markdown @tiptap/pm @tiptap/react @tiptap/starter-kit @tiptap/suggestion` |
 | `@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,8 +36,9 @@ 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/rich-chat-input` | `pnpm add @tiptap/core @tiptap/extension-highlight @tiptap/extension-image @tiptap/extension-list @tiptap/extension-mention @tiptap/extension-text-align @tiptap/extensions @tiptap/markdown @tiptap/pm @tiptap/react @tiptap/starter-kit @tiptap/suggestion date-fns` |
+| `@devalok/shilp-sutra/composed/diff` | `pnpm add react-syntax-highlighter` |
+| `@devalok/shilp-sutra/composed/rich-text-editor` | `pnpm add @tiptap/core @tiptap/extension-highlight @tiptap/extension-image @tiptap/extension-list @tiptap/extension-mention @tiptap/extension-text-align @tiptap/extensions @tiptap/markdown @tiptap/pm @tiptap/react @tiptap/starter-kit @tiptap/suggestion` |
 | `@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,8 +45,9 @@ 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/rich-chat-input` | `pnpm add @tiptap/core @tiptap/extension-highlight @tiptap/extension-image @tiptap/extension-list @tiptap/extension-mention @tiptap/extension-text-align @tiptap/extensions @tiptap/markdown @tiptap/pm @tiptap/react @tiptap/starter-kit @tiptap/suggestion date-fns` |
+| `@devalok/shilp-sutra/composed/diff` | `pnpm add react-syntax-highlighter` |
+| `@devalok/shilp-sutra/composed/rich-text-editor` | `pnpm add @tiptap/core @tiptap/extension-highlight @tiptap/extension-image @tiptap/extension-list @tiptap/extension-mention @tiptap/extension-text-align @tiptap/extensions @tiptap/markdown @tiptap/pm @tiptap/react @tiptap/starter-kit @tiptap/suggestion` |
 | `@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,8 +51,9 @@ 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/rich-chat-input` | `pnpm add @tiptap/core @tiptap/extension-highlight @tiptap/extension-image @tiptap/extension-list @tiptap/extension-mention @tiptap/extension-text-align @tiptap/extensions @tiptap/markdown @tiptap/pm @tiptap/react @tiptap/starter-kit @tiptap/suggestion date-fns` |
+| `@devalok/shilp-sutra/composed/diff` | `pnpm add react-syntax-highlighter` |
+| `@devalok/shilp-sutra/composed/rich-text-editor` | `pnpm add @tiptap/core @tiptap/extension-highlight @tiptap/extension-image @tiptap/extension-list @tiptap/extension-mention @tiptap/extension-text-align @tiptap/extensions @tiptap/markdown @tiptap/pm @tiptap/react @tiptap/starter-kit @tiptap/suggestion` |
 | `@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

@@ -196,17 +196,38 @@ In dev mode, calling `toast()` without a mounted `<Toaster />` logs a one-time c
 
 ## Symptom: Build error mentioning `use-sync-external-store`
 
-**Diagnosis:** Should not happen since v0.37.0 — `use-sync-external-store` was moved to runtime dependencies and is auto-installed transitively.
+**Diagnosis:** we no longer depend on it at all, as of v0.56.0. Nothing in our `dist` imports it.
 
-**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.
+It was never ours: React 18+ has `useSyncExternalStore` built in and our own code calls it directly. The dependency existed purely because we *bundled* TipTap, and that bundled chunk imported the shim. TipTap is now externalized, so the shim went with it.
 
-If it still happens, install it explicitly:
+If you still see the error, something else in your tree wants it — find out what and install it there:
 
 ```bash
-pnpm add use-sync-external-store
+pnpm why 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.
+If the trail leads back to `@devalok/shilp-sutra`, that's a bug: open an issue at <https://github.com/devalok-design/shilp-sutra/issues> with that output.
+
+## Symptom: `Cannot find module '@tiptap/core'` (or another `@tiptap/*`) after upgrading to 0.56.0
+
+**Diagnosis:** expected, and it is the one breaking change in 0.56.0. We used to bundle TipTap *and* list it as an optional peer — so `RichTextEditor` / `RichChatInput` worked whether or not you installed the peers. It is now externalized, so you must install them.
+
+**Why we changed it:** a consumer who *did* follow the peer instructions ended up running two ProseMirror copies. Plugin keys are module-scoped, so the two copies could not see each other's plugins and the editor misbehaved in ways that were near-impossible to debug. It also cut 641 KB from the package for everyone who never touches rich text.
+
+**Fix** — install the peers for the component you import (§2a of your framework's install recipe has the exact line):
+
+```bash
+# RichTextEditor
+pnpm add @tiptap/core @tiptap/extension-highlight @tiptap/extension-image \
+  @tiptap/extension-list @tiptap/extension-mention @tiptap/extension-text-align \
+  @tiptap/extensions @tiptap/markdown @tiptap/pm @tiptap/react \
+  @tiptap/starter-kit @tiptap/suggestion
+
+# RichChatInput — the same list plus date-fns
+pnpm add date-fns
+```
+
+Or ask the docs MCP: `preflight` reports exactly which peers your imports need.
 
 ## Symptom: `Cannot find package 'sonner'` when you only imported a hook (or `'react-markdown'` from the AI barrel)