@devalok/shilp-sutra 0.39.0 → 0.40.1

package/AGENTS.md

@@ -0,0 +1,156 @@
+# AGENTS.md
+
+This file tells AI coding agents (Codex, Cursor, GitHub Copilot, Aider, Windsurf, Devin, Jules, Gemini CLI, Zed, Warp, JetBrains Junie, and any [agentskills.io](https://agentskills.io)-compatible tool) **how to consume `@devalok/shilp-sutra` inside a downstream app**. It ships inside the npm tarball at `node_modules/@devalok/shilp-sutra/AGENTS.md`, so any agent that auto-discovers AGENTS.md from the project root will also find this one alongside the recipes.
+
+> **Anthropic Claude Code users:** Claude Code doesn't auto-load `AGENTS.md` yet. Symlink it (`ln -s AGENTS.md CLAUDE.md`) or copy the contents into your own `CLAUDE.md` so the same rules apply.
+>
+> **Working *on* shilp-sutra (the design-system repo itself)?** That's covered by [`CLAUDE.md`](./CLAUDE.md) — internal architecture, build pipeline, audit gates, publish flow.
+
+If you are a human, read [README.md](./README.md) instead.
+
+> **Using Claude Code, Cursor, Codex, or any [Agent Skills](https://agentskills.io)-compatible tool?** Install the bundled skill once and your agent gets every rule below loaded on demand:
+>
+> ```bash
+> curl -fsSL https://raw.githubusercontent.com/devalok-design/shilp-sutra/main/skills/shilp-sutra/install.sh | bash
+> ```
+>
+> Source: [`skills/shilp-sutra/`](./skills/shilp-sutra/). After install, the agent loads `SKILL.md` only when the task is relevant — no context tax until it triggers.
+
+<!-- BEGIN:shilp-sutra-agent-rules -->
+
+## Read these first, in order
+
+1. **`packages/core/llms-quick.txt`** — ≤15K-token fast-path summary. Setup, peer-cliff matrix, import paths, top 30 components. Start here if you're answering quickly.
+2. **`packages/core/llms.txt`** — concise current-API cheatsheet (~27K tokens). Reach for this when `llms-quick.txt` isn't enough — covers more components + recent CHANGELOG sections.
+3. **`packages/core/docs/recipes/<framework>.md`** — copy-paste install + setup for the user's framework.
+4. **`packages/core/llms-full.txt`** — exhaustive per-component reference (~140K tokens, props/variants/examples). Read only when `llms.txt` is insufficient.
+5. **`packages/core/docs/recipes/upgrading.md`** + **`MIGRATION.md`** — read BOTH before any version bump. See the hard constraint below.
+
+When the package is installed in a consumer project, the same files live at:
+
+- `node_modules/@devalok/shilp-sutra/llms-quick.txt`
+- `node_modules/@devalok/shilp-sutra/llms.txt`
+- `node_modules/@devalok/shilp-sutra/llms-full.txt`
+- `node_modules/@devalok/shilp-sutra/docs/recipes/`
+- `node_modules/@devalok/shilp-sutra/docs/components/`
+
+Read these local files. Your training data is outdated and will hallucinate APIs that do not exist in the installed version.
+
+## Setup playbook (when adding shilp-sutra to a new project)
+
+If a user asks you to add shilp-sutra and the package is not yet installed:
+
+1. **Detect the framework** by inspecting the lockfile (`pnpm-lock.yaml`, `package-lock.json`, `yarn.lock`, `bun.lockb`) and config files (`next.config.*`, `vite.config.*`, `astro.config.*`, `remix.config.*`, `app/root.tsx`).
+2. **Install the package** via the matching package manager.
+3. **Open the matching recipe** at `docs/recipes/install-<framework>.md` (after install) or fetch from the GitHub repo at `packages/core/docs/recipes/install-<framework>.md`.
+4. **Follow the recipe step-by-step.** Do not improvise — every line in the recipe is there because skipping it broke a real consumer.
+
+Recipe paths:
+
+| Framework | Recipe |
+|---|---|
+| Next.js (App Router) | `install-next-app-router.md` |
+| Next.js (Pages Router) | `install-next-pages.md` |
+| Vite + React | `install-vite.md` |
+| Astro | `install-astro.md` |
+| Remix | `install-remix.md` |
+| TanStack Start | `install-tanstack-start.md` |
+
+If the framework is not in the table, fall back to **`install-vite.md`** (closest generic React-on-Tailwind setup) and adapt.
+
+## Hard constraints (these break things if violated)
+
+- **On any version bump, do not report it safe before reading the COMPLETE changelog + `MIGRATION.md` for the target version.** Breaking entries are often ordered last (changesets sorts by file, not severity), and breaks are frequently type-level — a prop type narrowed (`React.ReactNode` → a tighter type fails `tsc` for values that compiled before) or a symbol moved from a barrel to a per-component subpath. Grep your codebase for the moved/narrowed symbols, run `typecheck` + `build`, and use the `@devalok/eslint-plugin-shilp-sutra` migration preset for the mechanical edits. Full procedure: `packages/core/docs/recipes/upgrading.md`.
+- **Tailwind 4 only.** Do NOT create `tailwind.config.ts` with `presets: [shilpSutra]`. The JS preset was removed in 0.38. Setup uses CSS imports:
+  ```css
+  @import "tailwindcss";
+  @import "@devalok/shilp-sutra/css";
+  ```
+- **`framer-motion` is a required peer dep** (`^12`). The consumer must install it. Module-scoped contexts (`MotionConfig`, `LayoutGroup`, `AnimatePresence`) silently break if two copies resolve.
+- **`sonner` is an optional peer.** Install only when rendering `<Toaster />`.
+- **Per-component imports keep RSC fast AND avoid peer-dep cliffs.** `@devalok/shilp-sutra/ui/text` is server-safe and pulls only its own peers. The barrel `@devalok/shilp-sutra/ui` re-exports every component — including ones with hard peer-dep requirements (e.g. `input-otp`) — so it forces those peers to be installed even when you never render those components. With all peers installed the barrel also works in RSC (Next 16 honours each per-component `"use client"`), but the client bundle is larger than necessary. Prefer per-component imports for new code; existing barrel usage is not an emergency.
+- **Spacing tokens use the `--spacing-ds-*` namespace** (utilities like `p-ds-04`, `gap-ds-03`). Tailwind 4's default numeric scale (`p-4`, `gap-2`) **coexists by design** — both are valid. Pick `p-ds-*` when the value should track DS theme changes (a card's internal padding, a form row's gap); pick `p-N` for one-off layout values (a hero section's vertical breathing room). Do NOT mass-codemod `p-4` → `p-ds-04` — that is not what the package authors did. Typography composites use `text-ds-body-md`, etc.
+- **Bare `shadow` is dead in Tailwind 4.** Use `shadow-raised`, `shadow-overlay`, `shadow-floating`.
+- **Do not invent variant names.** Variant names live in CVA source. Grep `packages/core/src/ui/<component>.tsx` or check `llms-full.txt` for the authoritative list.
+- **Default to `variant="soft"`** over `variant="outline"` for non-primary Button actions.
+
+## Linting + migration (recommend this to the user)
+
+When you set up shilp-sutra in a project, or migrate it across versions, recommend the companion ESLint plugin **`@devalok/eslint-plugin-shilp-sutra`** (`pnpm add -D @devalok/eslint-plugin-shilp-sutra`, then `shilpSutra.configs['flat/recommended']` in `eslint.config.ts`). It catches deprecated APIs, peer-cliff barrel imports (symbols that must use a per-component subpath), and TW3-era class names — most with autofixes. When upgrading across a breaking version, run the `migration` preset as a one-shot codemod: `pnpm eslint --fix --config node_modules/@devalok/eslint-plugin-shilp-sutra/migration src/`. Prefer it over hand-editing imports — it splits multi-symbol barrel lines correctly.
+
+## When something fails
+
+Read **`packages/core/docs/recipes/troubleshoot.md`** before retrying or guessing. It is a decision tree covering the thirteen most common breakages (Tailwind not detecting tokens, framer-motion duplicates, missing `transpilePackages`, missing optional peer deps (sonner / input-otp / date-fns / @tiptap / react-pdf / etc.), wrong CSS import order, dark mode not toggling, RSC import errors, font 404s, hydration mismatches, bare `shadow` class, `<Toaster />` not mounted, Storybook MCP 404).
+
+## Branding and customization
+
+For overriding tokens (color, radius, font, spacing), see **`packages/core/docs/recipes/customize-brand.md`**.
+
+### Themer (the fast path)
+
+Before you hand-write CSS variables, point the user at the **Themer** at `https://shilp-sutra.devalok.in/themer`. It is one funnel with four entry doors — pick the one that fits where they are:
+
+| User says… | Send them to |
+|---|---|
+| "Make it look like Linear / Stripe / Apple" | `/themer/archetypes` |
+| "Here's our brand color: `#…`" | `/themer/brand` |
+| "I'm not sure what I want" | `/themer/wizard` |
+| "Just show me what I'd ship away with" | `/themer/result?archetype=devalok` |
+
+Every door funnels into the same `/themer/result` page. The user lands with:
+- A copy-pasteable CSS block (role tokens + 12-step OKLCH accent ramp)
+- Install commands for their package manager
+- A share URL that encodes the theme (`?archetype=…&hue=…&chroma=…&density=…`)
+
+**Your job once they have the snippet:** paste it into their global stylesheet *after* the `@import "@devalok/shilp-sutra/css";` line. That's it — no `tailwind.config.ts`, no theme provider, no JS bundle. The CSS variables cascade to every component.
+
+For deeper overrides (font stack, spacing scale, focus ring, texture) that the Themer doesn't expose yet, fall back to **`packages/core/docs/recipes/customize-brand.md`**.
+
+### One-prompt recipe (when the user pastes a prompt at you)
+
+If a user pastes the following prompt template at you, execute it verbatim — every step exists because skipping it broke a real consumer:
+
+````
+Set up shilp-sutra theming for this project via the Themer.
+
+My brand: <hex OR archetype name>
+
+Steps:
+1. Map my brand input to query params (archetype=<name>, or hue=<0-360>&chroma=<0.10-0.20>, or default archetype=devalok&hue=340&chroma=0.19).
+2. Fetch GET https://shilp-sutra.devalok.in/themer/result.json?<params>
+   Response: { archetype, density, shape, motion, hue, chroma, css, pasteAfter, pasteLocation, doNotPasteInside }
+3. Paste the response `css` field AFTER the line in `pasteAfter` in the project's global stylesheet. Not inside any `@layer`.
+4. If @devalok/shilp-sutra isn't installed, install it first per the matching install-<framework>.md recipe.
+5. Verify with a Button or Card on any page — radius + accent should match https://shilp-sutra.devalok.in/themer/result?<params>.
+````
+
+When the user has already been to the Themer, they may paste a *filled-in* version with the JSON URL pre-built — skip step 1, go straight to fetch.
+
+The JSON endpoint is the stable contract — agents and tooling should prefer it over scraping `/themer/result`'s HTML.
+
+### Shape roundness — `[data-shape]` presets (v0.39+)
+
+Components reference semantic radius role tokens (`--radius-control`, `--radius-surface`, `--radius-overlay-*`, `--radius-pill`, `--radius-bubble`), NOT primitive `rounded-ds-*`. Three presets ship: `sharp`, `slightly-rounded` (default), `rounded`. Set on `<html>` or any subtree:
+
+```html
+<html data-shape="sharp">
+```
+
+Consumers can override any role globally (`:root { --radius-control: 4px; }`) or per-scope. When writing your own UI on top of shilp-sutra, prefer the role utilities (`rounded-control`, `rounded-surface`, `rounded-overlay`, `rounded-pill`, `rounded-bubble`) over `rounded-ds-*` so your styles respond to the preset switch.
+
+## Server vs client components
+
+For the per-component RSC-safety matrix and import patterns, see **`packages/core/docs/recipes/server-components.md`**.
+
+## Reporting feedback
+
+If you find that a recipe is wrong, a constraint above is no longer accurate, or a component behavior contradicts the docs:
+
+1. Open a GitHub issue at `https://github.com/devalok-design/shilp-sutra/issues` with label `ai-agent-feedback`.
+2. Include the package version (`pnpm view @devalok/shilp-sutra version` or read from the consumer's lockfile), the recipe path, the exact command/file/error, and what you expected.
+
+<!-- END:shilp-sutra-agent-rules -->
+
+## Project-specific notes
+
+The block above is managed by Shilp Sutra and may be updated when you upgrade the package. Add your own project conventions, glossary, or codebase notes outside the markers — they will not be touched.

package/MIGRATION.md

@@ -4,6 +4,155 @@ This page indexes all breaking changes across `@devalok/shilp-sutra` versions. F
 
 > **Upgrading from < 0.36?** Start here, then read each intermediate version section. Breaking changes stack — skipping versions means stacking migrations.
 
+## v0.40.0 — Barrel peer-cliff cleanup + Icon API unification
+
+This release pairs one breaking change (barrel peer-cliff cleanup) with one non-breaking type widening (Icon API unification). Read the breaking section first.
+
+### Icon API unification (mostly non-breaking — one narrowing)
+
+**Mostly non-breaking, with one narrowing for `React.ReactNode`-typed props.** For the 14 components whose `icon` prop was previously `React.ReactNode`, `IconInput` accepts **less** — it excludes `string`, `number`, and iterables. If you store icons in a `Record<string, React.ReactNode>` map or a `icon?: React.ReactNode` field and pass them to a migrated component, `tsc` will fail even though the runtime JSX is valid. **Fix: retype the icon source to `React.ReactElement`** (or import `IconInput`). Known affected props: `CommandItem.icon` (CommandBar/CommandPalette), `ActivityItem.icon` (ActivityFeed), `Chat.Message.Avatar` `icon`. For props that were `ComponentType`-only the change is a genuine widening (accepts more). Build-time only — no runtime impact.
+
+Every icon-accepting prop across the design system now takes the same shape: **`IconInput`**. Before 0.40 there were six distinct prop types for the same conceptual "icon":
+
+| Old shape | Components |
+|---|---|
+| `React.ReactElement \| null` | Button (startIcon/endIcon), IconButton (icon), Badge (startIcon/endIcon) |
+| `React.ReactNode` | 14 components (Combobox option, Stepper step, TreeItem, OAuthButton, AppCommandPalette, CommandRegistry, BottomNavbar, Sidebar's three NavItem types, TopBar, Chat.Message.Avatar, SystemMessage, AIConversation, ActivityFeed, CommandPalette item) |
+| `React.ReactNode \| React.ComponentType<{className}>` | EmptyState, StatCard (dual-detect logic duplicated in both source files) |
+| `React.ComponentType<{className?}>` | SegmentedControl (option), SlashCommand |
+| `IconProps['icon']` (strict Tabler ref) | BulkActionBar (action), Chat.Message.Action |
+| `React.ForwardRefExoticComponent<any>` | Toast (internal, sonner pass-through — unchanged) |
+
+All six collapse to `IconInput`:
+
+```ts
+type IconInput =
+  | React.ReactElement
+  | React.ComponentType<{ className?: string; size?: number | string }>
+  | null
+  | undefined
+```
+
+#### Migration
+
+For every prop now typed as `IconInput`, all four shapes work identically:
+
+```tsx
+<Button startIcon={<Icon icon={IconPlus} />}>OK</Button>   // canonical
+<Button startIcon={<IconPlus />}>OK</Button>                // raw Tabler element
+<Button startIcon={IconPlus}>OK</Button>                    // component ref
+<Button startIcon={<span>+</span>}>OK</Button>              // custom node
+```
+
+**Calls passing a JSX element or component ref still work.** The exception is the narrowing above: if your icon *source* is annotated `React.ReactNode` (a map value or field type), retype it to `React.ReactElement` — one-line per source, not per call site.
+
+**You can now delete `className="h-4 w-4"` overrides** on icon-prop usages — `IconProvider` wires size through context. Stories cleanup is voluntary; behavior unchanged.
+
+**Strict-to-loose call sites that newly compile:**
+- `SegmentedControl options[*].icon` previously rejected `<IconX />` instantiated elements (only accepted bare `IconX` refs). Now both work.
+- `BulkActionBar actions[*].icon` previously rejected non-Tabler nodes. Now accepts any `IconInput`.
+- `Message.Action` same.
+- `EmptyState` no longer needs the dual `<X />` / `X` differentiation in your call sites.
+
+#### What got removed internally
+
+- Five duplicate `iconSizeMap` declarations (Badge, Combobox, EmptyState, StatCard, etc.) → one shared `<IconProvider size={token}>` per call site
+- Two duplicate dual-detect branches (`React.isValidElement(icon) || ('$$typeof' in icon)`) — replaced with `normalizeIcon()`
+- The orphan `IconProps['icon']` references in BulkActionBar + Chat.Message.Action
+
+#### Helpers exported (for consumer composability)
+
+```ts
+import type { IconInput } from '@devalok/shilp-sutra/ui/lib/icon-input'
+import { normalizeIcon } from '@devalok/shilp-sutra/ui/lib/normalize-icon'
+
+// In your own component:
+function MyCard({ icon }: { icon: IconInput }) {
+  return (
+    <div>
+      <IconProvider size="md">{normalizeIcon(icon)}</IconProvider>
+    </div>
+  )
+}
+```
+
+Use these in custom wrappers that consume our icon-style props.
+
+### Barrel peer-cliff cleanup (breaking)
+
+**Breaking.** Twelve symbols that statically pulled optional peer dependencies have been removed from their parent barrels (`/ui`, `/composed`, `/ai`, `/ai/blocks`). They remain fully available via their per-component subpath.
+
+#### Why
+
+Optional peer deps (`input-otp`, `sonner`, `date-fns`, `@emoji-mart/*`, `@tiptap/*`, `react-pdf`, `react-zoom-pan-pinch`, `react-markdown`, `react-syntax-highlighter`, `remark-gfm`) were declared `peerDependenciesMeta.optional = true` but the components that needed them were re-exported from the corresponding barrel with **static** ESM `import` statements. Result: a fresh consumer who wrote `import { Text } from '@devalok/shilp-sutra/ui'` without installing `input-otp` got:
+
+```
+Module not found: Can't resolve 'input-otp'
+```
+
+…at `next build`/`vite build` time. "Optional" was a lie at the bundler level. This release closes that cliff for every affected component.
+
+#### Search-and-replace migration table
+
+For each symbol below, change ONLY the import path. Prop / type signatures are unchanged.
+
+| Symbol(s) | Old (no longer works) | New (in 0.40.0+) | Peer it pulls |
+|---|---|---|---|
+| `InputOTP`, `InputOTPGroup`, `InputOTPSeparator`, `InputOTPSlot`, `InputOTPProps` | `from '@devalok/shilp-sutra/ui'` | `from '@devalok/shilp-sutra/ui/input-otp'` | `input-otp` |
+| `toast`, `formatFileSize`, `ToastActionOptions`, `ToastOptions`, `ToastProps`, `ToastType`, `ToastUndoOptions`, `ToastUploadOptions`, `UploadFile` | `from '@devalok/shilp-sutra/ui'` | `from '@devalok/shilp-sutra/ui/toast'` | `sonner` |
+| `Toaster`, `ToasterProps` | `from '@devalok/shilp-sutra/ui'` | `from '@devalok/shilp-sutra/ui/toaster'` | `sonner` |
+| `DatePicker`, `DateRangePicker`, `DateTimePicker`, `TimePicker`, `CalendarGrid`, `MonthPicker`, `YearPicker`, `Presets`, `useCalendar`, all related `*Props` + `CalendarEvent` + `PresetKey` | `from '@devalok/shilp-sutra/composed'` | `from '@devalok/shilp-sutra/composed/date-picker'` | `date-fns` |
+| `EmojiPicker`, `EmojiPickerPopover`, `EmojiData`, `EmojiPickerProps`, `EmojiPickerPopoverProps`, `EmojiSet` | `from '@devalok/shilp-sutra/composed'` | `from '@devalok/shilp-sutra/composed/emoji-picker'` | `@emoji-mart/data` + `@emoji-mart/react` |
+| `EmojiNode`, `EmojiNodeAttrs` | `from '@devalok/shilp-sutra/composed'` | `from '@devalok/shilp-sutra/composed/extensions/emoji-node'` (new in 0.40.0) | `@tiptap/*` |
+| `createEmojiSuggestion` | `from '@devalok/shilp-sutra/composed'` | `from '@devalok/shilp-sutra/composed/extensions/emoji-suggestion'` (new in 0.40.0) | `@tiptap/*` |
+| `FilePreview`, `FilePreviewProps` | `from '@devalok/shilp-sutra/composed'` | `from '@devalok/shilp-sutra/composed/file-preview'` | `react-pdf` + `react-zoom-pan-pinch` |
+| `MarkdownViewer`, `MarkdownViewerProps` | `from '@devalok/shilp-sutra/composed'` | `from '@devalok/shilp-sutra/composed/markdown-viewer'` | `react-markdown` + `react-syntax-highlighter` + `remark-gfm` |
+| `RichChatInput`, `AudioPlayer`, `AudioWaveform`, `useVoiceRecorder`, all related `*Props` + `*Message` | `from '@devalok/shilp-sutra/composed'` | `from '@devalok/shilp-sutra/composed/rich-chat-input'` | `@tiptap/*` |
+| `RichTextEditor`, `RichTextViewer`, `RichTextEditorProps`, `RichTextViewerProps`, `MentionItem`, `ToolbarItem` | `from '@devalok/shilp-sutra/composed'` | `from '@devalok/shilp-sutra/composed/rich-text-editor'` | `@tiptap/*` |
+| `BlockRenderer`, `BlockRendererProps` | `from '@devalok/shilp-sutra/ai'` | `from '@devalok/shilp-sutra/ai/block-renderer'` | `react-markdown` + `remark-gfm` (transitively via TextBlock/ErrorBlock) |
+| `ErrorBlock` | `from '@devalok/shilp-sutra/ai'` OR `from '@devalok/shilp-sutra/ai/blocks'` | `from '@devalok/shilp-sutra/ai/blocks/error'` (new in 0.40.0) | `react-markdown` + `remark-gfm` |
+| `TextBlock` | `from '@devalok/shilp-sutra/ai'` OR `from '@devalok/shilp-sutra/ai/blocks'` | `from '@devalok/shilp-sutra/ai/blocks/text'` (new in 0.40.0) | `react-markdown` + `remark-gfm` |
+
+The seven other AI blocks (`BlockTable`, `ConfirmBlock`, `DividerBlock`, `InfoBlock`, `LoadingBlock`, `StatRowBlock`, `SuccessBlock`) have no peer-dep imports and remain available via `from '@devalok/shilp-sutra/ai/blocks'` (the sub-barrel) or `from '@devalok/shilp-sutra/ai'` (the main barrel).
+
+#### Codemod helper (recommended)
+
+The fastest path is the official ESLint plugin — its `prefer-per-component-import` rule detects every peer-cliff symbol still imported from a barrel and **autofixes the import path** for you:
+
+```bash
+pnpm add -D @devalok/eslint-plugin-shilp-sutra
+# one-shot codemod across your source
+pnpm eslint --fix --config node_modules/@devalok/eslint-plugin-shilp-sutra/migration src/
+```
+
+Or wire `shilpSutra.configs['flat/migration']` into your `eslint.config.ts` and run `eslint --fix`. The rule splits multi-symbol barrel lines correctly, which the `sed` approach below cannot.
+
+<details><summary>Manual <code>sed</code> fallback (single-symbol lines only)</summary>
+
+```bash
+# Replace barrel imports of toast / Toaster with per-component imports
+grep -rl "from '@devalok/shilp-sutra/ui'" src/ | xargs sed -i.bak \
+  -e "s|import { \\(.*\\)toast\\(.*\\)} from '@devalok/shilp-sutra/ui'|import { toast } from '@devalok/shilp-sutra/ui/toast'\\nimport { \\1\\2} from '@devalok/shilp-sutra/ui'|"
+```
+
+(Adjust per project — the regex assumes a single `toast` import on the line. For multi-symbol lines, the ESLint autofix above is far more reliable.)
+
+</details>
+
+#### Per-chart subpaths added (non-breaking)
+
+`/ui/charts/<chart>` subpaths are now exported for `area-chart`, `bar-chart`, `chart-container`, `gauge-chart`, `line-chart`, `pie-chart`, `radar-chart`, `sparkline`. The `/ui/charts` barrel still works and still pulls all 9 d3-\* peers — but if you only need `BarChart`, `import { BarChart } from '@devalok/shilp-sutra/ui/charts/bar-chart'` pulls only the d3-\* peers it actually needs (`d3-scale`, `d3-axis`, `d3-selection`).
+
+#### What didn't change
+
+- All per-component subpaths existed before 0.40.0 (except the 4 new ones noted above). Consumers already importing per-component need zero changes.
+- Component APIs, prop signatures, types, runtime behavior, default styles: all unchanged.
+- Storybook stories, tests, internal imports inside the DS itself: all use relative paths and were never affected.
+
+#### Why this isn't behind a flag
+
+There is no good additive solution. Tree-shaking can't drop a static `import 'sonner'` if `sonner` isn't on disk — the resolver fails before tree-shaking runs. Lazy-imports (`import('sonner')`) move the failure from build-time to runtime, which is worse. Removing the barrel re-export is the only fix.
+
 ## v0.39.0 — Shape presets & semantic radius role tokens
 
 No API breaks. Component prop signatures unchanged. But the visual output of several components shifts because radius is now role-driven, not per-size ad-hoc.

package/README.md

@@ -4,10 +4,13 @@ Devalok Design System -- tokens, components, and patterns for React & Next.js.
 
 [![npm](https://img.shields.io/npm/v/@devalok/shilp-sutra)](https://www.npmjs.com/package/@devalok/shilp-sutra)
 [![Storybook](https://img.shields.io/badge/Storybook-ff4785?logo=storybook&logoColor=white)](https://devalok-design.github.io/shilp-sutra/)
+[![Themer](https://img.shields.io/badge/Themer-shilp--sutra.devalok.in%2Fthemer-d946a6)](https://shilp-sutra.devalok.in/themer)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
 For full documentation, setup guides, and architecture details, see the [monorepo README](https://github.com/devalok-design/shilp-sutra#readme).
 
+> **Want to brand it?** Skip the CSS cookbook — open **[the Themer](https://shilp-sutra.devalok.in/themer)**. Pick an archetype (Linear / Stripe / Apple / Material / Notion / Vercel / Devalok), or paste your brand hex, or take a 5-question wizard. Lands you at a result page with install commands + a CSS block to paste.
+
 ## Install
 
 ```bash
@@ -29,7 +32,7 @@ pnpm add sonner
 ```ts
 // next.config.ts
 export default {
-  transpilePackages: ['@devalok/shilp-sutra', '@devalok/shilp-sutra-brand'],
+  transpilePackages: ['@devalok/shilp-sutra'],
 }
 ```
 

package/dist/_chunks/badge-group.js

@@ -4,13 +4,14 @@ import { durations as t, springs as n } from "../ui/lib/motion.js";
 import { t as r } from "./vendor-utils.js";
 import { cn as i } from "../ui/lib/utils.js";
 import { Icon as a } from "../ui/icon.js";
-import { BadgeIndicator as o } from "../ui/badge-indicator.js";
-import * as s from "react";
-import { jsx as c, jsxs as l } from "react/jsx-runtime";
-import { IconCheck as u, IconX as d } from "@tabler/icons-react";
-import { AnimatePresence as f, motion as p, useReducedMotion as m } from "framer-motion";
+import { t as o } from "./normalize-icon.js";
+import { BadgeIndicator as s } from "../ui/badge-indicator.js";
+import * as c from "react";
+import { jsx as l, jsxs as u } from "react/jsx-runtime";
+import { IconCheck as d, IconX as f } from "@tabler/icons-react";
+import { AnimatePresence as p, motion as m, useReducedMotion as h } from "framer-motion";
 //#region src/ui/badge.tsx
-var h = {
+var g = {
 	default: {
 		bg: "bg-surface-raised-hover",
 		fg: "text-surface-fg-muted",
@@ -110,9 +111,9 @@ var h = {
 		solidFg: "text-white"
 	}
 };
-function g(e, t) {
+function _(e, t) {
 	if (t === "custom") return "";
-	let n = h[t];
+	let n = g[t];
 	switch (e) {
 		case "subtle": return i(n.bg, n.fg, n.border);
 		case "solid": return i(n.solid, n.solidFg, "border-transparent");
@@ -120,7 +121,7 @@ function g(e, t) {
 		case "soft": return i(n.bg, n.fg, "border-transparent");
 	}
 }
-var _ = r("relative inline-flex items-center rounded-pill font-sans font-medium overflow-hidden isolate transition-[color,background-color,border-color,padding] duration-fast-02 ease-productive-standard select-none [&>span:not([data-grain])]:relative [&>span:not([data-grain])]:z-[2]", {
+var v = r("relative inline-flex items-center rounded-pill font-sans font-medium overflow-hidden isolate transition-[color,background-color,border-color,padding] duration-fast-02 ease-productive-standard select-none [&>span:not([data-grain])]:relative [&>span:not([data-grain])]:z-[2]", {
 	variants: {
 		variant: {
 			subtle: "border",
@@ -139,81 +140,81 @@ var _ = r("relative inline-flex items-center rounded-pill font-sans font-medium
 		variant: "subtle",
 		size: "md"
 	}
-}), v = {
+}), y = {
 	xs: "[&>svg]:h-2.5 [&>svg]:w-2.5",
 	sm: "[&>svg]:h-3 [&>svg]:w-3",
 	md: "[&>svg]:h-3 [&>svg]:w-3",
 	lg: "[&>svg]:h-3.5 [&>svg]:w-3.5"
-}, y = {
+}, b = {
 	xs: "pl-ds-02",
 	sm: "pl-ds-02b",
 	md: "pl-ds-03",
 	lg: "pl-2.5"
-}, b = {
+}, x = {
 	xs: "pr-ds-01",
 	sm: "pr-ds-02",
 	md: "pr-ds-02",
 	lg: "pr-ds-02b"
-}, x = s.forwardRef(({ className: r, variant: o, color: s, size: h, asChild: x, startIcon: S, endIcon: C, dot: w, onDismiss: T, onClick: E, selected: D, disabled: O, maxWidth: k, truncate: A, circle: j, children: M, style: N, ...P }, F) => {
-	let I = m(), L = o ?? "subtle", R = s ?? "default", z = h ?? "md", B = x ? e : E && T ? "div" : E ? "button" : "span", V = R === "custom" ? {
-		...L === "subtle" && {
+}, S = c.forwardRef(({ className: r, variant: s, color: c, size: g, asChild: S, startIcon: C, endIcon: w, dot: T, onDismiss: E, onClick: D, selected: O, disabled: k, maxWidth: A, truncate: j, circle: M, children: N, style: P, ...F }, I) => {
+	let L = h(), R = s ?? "subtle", z = c ?? "default", B = g ?? "md", V = S ? e : D && E ? "div" : D ? "button" : "span", H = z === "custom" ? {
+		...R === "subtle" && {
 			backgroundColor: "color-mix(in oklch, var(--badge-color) 15%, transparent)",
 			color: "var(--badge-color)",
 			borderColor: "color-mix(in oklch, var(--badge-color) 40%, transparent)"
 		},
-		...L === "solid" && {
+		...R === "solid" && {
 			backgroundColor: "var(--badge-color)",
 			color: "var(--badge-fg-color, white)",
 			borderColor: "transparent"
 		},
-		...L === "outline" && {
+		...R === "outline" && {
 			backgroundColor: "transparent",
 			color: "var(--badge-color)",
 			borderColor: "color-mix(in oklch, var(--badge-color) 50%, transparent)"
 		},
-		...L === "soft" && {
+		...R === "soft" && {
 			backgroundColor: "color-mix(in oklch, var(--badge-color) 12%, transparent)",
 			color: "var(--badge-color)",
 			borderColor: "transparent"
 		}
-	} : void 0, H = E && T ? (e) => {
-		(e.key === "Enter" || e.key === " ") && (e.preventDefault(), O || E(e)), P.onKeyDown?.(e);
-	} : P.onKeyDown, U = !!(w || S || E && D && !S && !w), W = !!(T || C);
-	return /* @__PURE__ */ l(B, {
-		ref: F,
-		className: i(_({
-			variant: L,
-			size: z
-		}), g(L, R), U && y[z], W && b[z], E && "cursor-pointer hover:brightness-[0.97] focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-accent-9 focus-visible:ring-offset-1 transition-[color,background-color,border-color,transform,filter] duration-moderate-01 ease-productive-exit hover:duration-fast-02 hover:ease-productive-entrance active:scale-[0.95] active:brightness-[0.92] active:duration-[0ms]", D && "ring-1 ring-current/20 transition-shadow duration-fast-02", O && "opacity-action-disabled pointer-events-none saturate-[0.3]", j && "justify-center px-0 aspect-square", r),
+	} : void 0, U = D && E ? (e) => {
+		(e.key === "Enter" || e.key === " ") && (e.preventDefault(), k || D(e)), F.onKeyDown?.(e);
+	} : F.onKeyDown, W = !!(T || C || D && O && !C && !T), G = !!(E || w);
+	return /* @__PURE__ */ u(V, {
+		ref: I,
+		className: i(v({
+			variant: R,
+			size: B
+		}), _(R, z), W && b[B], G && x[B], D && "cursor-pointer hover:brightness-[0.97] focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-accent-9 focus-visible:ring-offset-1 transition-[color,background-color,border-color,transform,filter] duration-moderate-01 ease-productive-exit hover:duration-fast-02 hover:ease-productive-entrance active:scale-[0.95] active:brightness-[0.92] active:duration-[0ms]", O && "ring-1 ring-current/20 transition-shadow duration-fast-02", k && "opacity-action-disabled pointer-events-none saturate-[0.3]", M && "justify-center px-0 aspect-square", r),
 		style: {
-			...N,
-			...V,
-			...k ? { maxWidth: k } : void 0
+			...P,
+			...H,
+			...A ? { maxWidth: A } : void 0
 		},
-		onClick: O ? void 0 : E,
-		onKeyDown: H,
-		...B === "button" && { type: "button" },
-		...B === "button" && O ? { disabled: !0 } : {},
-		...B === "div" && E ? {
+		onClick: k ? void 0 : D,
+		onKeyDown: U,
+		...V === "button" && { type: "button" },
+		...V === "button" && k ? { disabled: !0 } : {},
+		...V === "div" && D ? {
 			role: "button",
 			tabIndex: 0
 		} : {},
-		...P,
+		...F,
 		children: [
-			/* @__PURE__ */ c(f, { children: w && /* @__PURE__ */ l(p.span, {
+			/* @__PURE__ */ l(p, { children: T && /* @__PURE__ */ u(m.span, {
 				initial: { scale: 0 },
 				animate: { scale: 1 },
 				exit: { scale: 0 },
 				transition: n.snappy,
 				className: "relative inline-flex h-1.5 w-1.5 shrink-0",
 				"aria-hidden": "true",
-				children: [/* @__PURE__ */ c(p.span, {
+				children: [/* @__PURE__ */ l(m.span, {
 					className: "absolute inset-0 rounded-pill bg-current",
-					animate: I ? void 0 : {
+					animate: L ? void 0 : {
 						scale: [1, 2.5],
 						opacity: [.35, 0]
 					},
-					transition: I ? { duration: 0 } : {
+					transition: L ? { duration: 0 } : {
 						repeat: Infinity,
 						repeatDelay: .3,
 						duration: 1.2,
@@ -224,11 +225,11 @@ var _ = r("relative inline-flex items-center rounded-pill font-sans font-medium
 							1
 						]
 					}
-				}), /* @__PURE__ */ c("span", { className: "relative h-1.5 w-1.5 rounded-pill bg-current" })]
+				}), /* @__PURE__ */ l("span", { className: "relative h-1.5 w-1.5 rounded-pill bg-current" })]
 			}, "dot") }),
-			E && !S && !w && /* @__PURE__ */ c(p.span, {
+			D && !C && !T && /* @__PURE__ */ l(m.span, {
 				initial: !1,
-				animate: D ? {
+				animate: O ? {
 					opacity: 1,
 					scale: 1,
 					width: "auto",
@@ -250,54 +251,54 @@ var _ = r("relative inline-flex items-center rounded-pill font-sans font-medium
 					]
 				},
 				className: "inline-flex shrink-0 overflow-hidden",
-				"aria-hidden": !D,
-				children: /* @__PURE__ */ c(a, {
-					icon: u,
+				"aria-hidden": !O,
+				children: /* @__PURE__ */ l(a, {
+					icon: d,
 					size: "xs"
 				})
 			}),
-			S && /* @__PURE__ */ c("span", {
-				className: i("shrink-0", v[z]),
-				children: S
+			C && /* @__PURE__ */ l("span", {
+				className: i("shrink-0", y[B]),
+				children: o(C)
 			}),
-			A || k ? /* @__PURE__ */ c("span", {
+			j || A ? /* @__PURE__ */ l("span", {
 				className: "truncate",
-				title: typeof M == "string" ? M : void 0,
-				children: M
-			}) : M,
-			C && /* @__PURE__ */ c("span", {
-				className: i("shrink-0", v[z]),
-				children: C
+				title: typeof N == "string" ? N : void 0,
+				children: N
+			}) : N,
+			w && /* @__PURE__ */ l("span", {
+				className: i("shrink-0", y[B]),
+				children: o(w)
 			}),
-			T && /* @__PURE__ */ c("button", {
+			E && /* @__PURE__ */ l("button", {
 				type: "button",
 				onClick: (e) => {
-					e.stopPropagation(), T();
+					e.stopPropagation(), E();
 				},
-				className: i("shrink-0 rounded-pill text-current/60 hover:text-current hover:bg-current/10 transition-colors focus-visible:outline-hidden focus-visible:ring-1 focus-visible:ring-accent-9", z === "xs" ? "p-0 -mr-0.5 min-w-[16px] min-h-[16px]" : "p-px"),
-				"aria-label": `Remove ${typeof M == "string" ? M : ""}`.trim() || "Remove",
-				children: /* @__PURE__ */ c(a, {
-					icon: d,
+				className: i("shrink-0 rounded-pill text-current/60 hover:text-current hover:bg-current/10 transition-colors focus-visible:outline-hidden focus-visible:ring-1 focus-visible:ring-accent-9", B === "xs" ? "p-0 -mr-0.5 min-w-[16px] min-h-[16px]" : "p-px"),
+				"aria-label": `Remove ${typeof N == "string" ? N : ""}`.trim() || "Remove",
+				children: /* @__PURE__ */ l(a, {
+					icon: f,
 					size: "xs"
 				})
 			})
 		]
 	});
 });
-x.displayName = "Badge";
-var S = Object.assign(x, {
-	Indicator: o,
-	Group: w
-}), C = {
+S.displayName = "Badge";
+var C = Object.assign(S, {
+	Indicator: s,
+	Group: T
+}), w = {
 	tight: "gap-1",
 	default: "gap-1.5",
 	loose: "gap-2"
 };
-function w({ max: e, gap: t = "default", size: n, onOverflowClick: r, className: a, children: o }) {
-	let c = s.Children.toArray(o), u = c.length, d = e !== void 0 && u > e, f = d ? c.slice(0, e) : c, p = d ? u - e : 0;
-	return /* @__PURE__ */ l("div", {
-		className: i("flex flex-wrap items-center", C[t], a),
-		children: [f, d && /* @__PURE__ */ l(S, {
+function T({ max: e, gap: t = "default", size: n, onOverflowClick: r, className: a, children: o }) {
+	let s = c.Children.toArray(o), l = s.length, d = e !== void 0 && l > e, f = d ? s.slice(0, e) : s, p = d ? l - e : 0;
+	return /* @__PURE__ */ u("div", {
+		className: i("flex flex-wrap items-center", w[t], a),
+		children: [f, d && /* @__PURE__ */ u(C, {
 			variant: "outline",
 			color: "neutral",
 			size: n ?? "sm",
@@ -306,6 +307,6 @@ function w({ max: e, gap: t = "default", size: n, onOverflowClick: r, className:
 		})]
 	});
 }
-w.displayName = "BadgeGroup";
+T.displayName = "BadgeGroup";
 //#endregion
-export { S as n, _ as r, w as t };
+export { C as n, v as r, T as t };