@devalok/shilp-sutra 0.55.1 → 0.57.0

package/docs/components/shell/app-shell.md

@@ -0,0 +1,132 @@
+# AppShell
+
+- Import: @devalok/shilp-sutra/shell/app-shell
+- Server-safe: No
+- Category: shell
+
+## Overview
+
+The frame that lets a bar span above **both** the sidebar and the content.
+
+`SidebarProvider` renders a single flex row, so a bar can only live *inside* the
+content pane — which is why every shadcn example puts its `<header>` inside
+`SidebarInset`. AppShell is the other arrangement: the bar is a sibling above the
+row, the way Carbon's `Header` sits above its `SideNav`.
+
+It provides layout and surfaces only. Put `TopBar` in the bar slot and compose
+the `Sidebar` primitives in the sidebar slot — AppShell does not replace either.
+
+## Subcomponents
+
+| Component | Purpose |
+|-----------|---------|
+| `AppShell` | Root — owns the chrome surface and the arrangement |
+| `AppShellBar` | Full-width bar above everything. Minimum height, never fixed. |
+| `AppShellBody` | The row beneath the bar: sidebar alongside canvas |
+| `AppShellSidebar` | Fixed-width slot, 16rem or 3rem collapsed |
+| `AppShellCanvas` | The content pane; becomes an inset panel when `variant="inset"` |
+
+## Props
+
+### AppShell
+    variant?: 'flat' | 'inset'
+    chrome?: 'dim' | 'bright'
+    className?: string
+
+Defaults: `variant` is `flat`, `chrome` is `dim`. `chrome` only applies when
+`variant="inset"`.
+
+### AppShellBar
+    bordered?: boolean
+    className?: string
+
+Defaults: `bordered` is `true` when the shell is flat and `false` when inset.
+
+### AppShellSidebar
+    collapsed?: boolean
+    className?: string
+
+Defaults: `collapsed` is `false` — 16rem expanded, 3rem collapsed.
+
+### AppShellBody / AppShellCanvas
+    className?: string
+
+## Example
+
+```tsx
+import {
+  AppShell, AppShellBar, AppShellBody, AppShellCanvas, AppShellSidebar,
+} from '@devalok/shilp-sutra/shell/app-shell'
+import { TopBar } from '@devalok/shilp-sutra/shell/top-bar'
+
+export function Layout({ children }) {
+  return (
+    <AppShell variant="inset" chrome="dim">
+      <AppShellBar>
+        <TopBar>
+          <TopBar.Left><TopBar.Title>Projects</TopBar.Title></TopBar.Left>
+          <TopBar.Right><TopBar.UserMenu user={user} /></TopBar.Right>
+        </TopBar>
+      </AppShellBar>
+
+      <AppShellBody>
+        <AppShellSidebar>
+          <Nav />
+        </AppShellSidebar>
+        <AppShellCanvas className="overflow-auto">
+          {children}
+        </AppShellCanvas>
+      </AppShellBody>
+    </AppShell>
+  )
+}
+```
+
+## The three arrangements
+
+**`variant="flat"`** — chrome and content share one surface; a hairline on the
+sidebar and under the bar does the separating. Widest content area.
+
+**`variant="inset"`** — the content sits in a rounded panel inside the chrome.
+`chrome` then decides which plane the frame takes and which the work takes:
+
+| | light chrome | light canvas | dark chrome | dark canvas |
+|---|---|---|---|---|
+| `chrome="dim"` | `#eeeeee` | `#ffffff` | `#0a0a0a` | `#171717` |
+| `chrome="bright"` | `#ffffff` | `#eeeeee` | `#171717` | `#0a0a0a` |
+
+Both come from the same two tokens — `surface-sunken` and `surface-panel` —
+swapped. There is no third tier and no per-theme special case.
+
+The choice is not really about lightness. With `dim` a brand tint lands on the
+frame and the work area stays neutral; with `bright` it is the reverse. That
+decides whether your brand colour surrounds the work or sits underneath it.
+
+## Composability
+
+Layout only. It sets surfaces, widths and the inset geometry; everything inside
+each slot is yours. Any component can go in any slot.
+
+`AppShellSidebar` uses the same widths as `Sidebar` (16rem, 3rem collapsed), so
+the two agree whether or not you nest one inside the other.
+
+## Gotchas
+
+**The bar height is a minimum, not a fixed value.** `TopBar` sizes to its
+content, and a two-line workspace switcher legitimately needs more room than a
+one-line one. Setting a fixed height clips it.
+
+**The inset canvas is flush to the bar and the sidebar** and floats only off the
+bottom-right. That is deliberate: it reads as the frame opening up rather than a
+card dropped into the middle. A symmetric gap fights that.
+
+**No shadow on the inset canvas.** It is a frame, not a floating thing — shadows
+are reserved for what genuinely floats (menus, dialogs, popovers).
+
+**A bar is optional, and dropping it is a product decision.** Without one, the
+account and workspace switcher move into the sidebar footer. That changes what
+the shell is for, not just how it looks.
+
+## Changes
+
+- 0.57.0 — added

package/docs/components/ui/avatar.md

@@ -38,7 +38,7 @@
 - **Status + Ring + Badge are independent** — you can stack all three on one Avatar. They render in separate layers so they don't conflict visually.
 - **Use with AvatarGroup:** AvatarGroup applies its own `size` to children. If your Avatar has an explicit `size`, it overrides AvatarGroup's default — keep it consistent across the group.
 - **AvatarFallback colorSeed:** Deterministic background color from the seed string — identical user IDs produce identical backgrounds across renders. Useful for user-identifying avatars without photos.
-- **Ring offset color:** The ring renders with `ring-offset` matching the current surface — it assumes the Avatar sits on `bg-surface-raised`. On other backgrounds, add a ring-offset className to compensate.
+- **Ring offset color:** The ring renders with `ring-offset` matching the current surface — it assumes the Avatar sits on `bg-surface-panel`. On other backgrounds, add a ring-offset className to compensate.
 
 ## Gotchas
 - Status dot renders with role="img" and aria-label (accessible, not decorative)

package/docs/components/ui/button.md

@@ -44,7 +44,7 @@
 - **Prefer `variant="soft"` over `variant="outline"` for secondary actions** (see Gotchas for details). This is a design-system-wide convention.
 
 ## Gotchas
-- **Prefer `variant="soft"` over `variant="outline"` for secondary actions.** Soft (tinted step-3 bg, step-11 text) is the Devalok-recommended default — it feels warmer and brand-consistent. Use `outline` only when soft's tint would disappear (on colored/surface-raised bg), in toolbar/icon-dense contexts, or when you need outline's stronger hierarchy next to a primary action.
+- **Prefer `variant="soft"` over `variant="outline"` for secondary actions.** Soft (tinted step-3 bg, step-11 text) is the Devalok-recommended default — it feels warmer and brand-consistent. Use `outline` only when soft's tint would disappear (on colored/surface-panel bg), in toolbar/icon-dense contexts, or when you need outline's stronger hierarchy next to a primary action.
 - DO NOT use variant="destructive" — use variant="solid" color="error"
 - DO NOT use variant="secondary" — use variant="soft" (preferred) or variant="ghost"
 - DO NOT use size="default" — use size="md"

package/docs/components/ui/chat.md

@@ -155,13 +155,16 @@ Horizontal rule with a formatted date label.
 
 ### Props
     date: Date | string (REQUIRED)
-    format: (date: Date) => string — custom date formatter
+    format: (date: Date) => string — custom date formatter (overrides locale/timeZone)
+    locale: string — BCP 47 locale for the default label's month name (default 'en-US')
+    timeZone: string — IANA time zone for the "Today"/"Yesterday" day-boundary comparison and formatting (default: browser's local time zone)
     className: string
 
 ### Example
 ```jsx
 <DateSeparator date={new Date()} />
 <DateSeparator date="2026-03-25" format={(d) => d.toLocaleDateString()} />
+<DateSeparator date={new Date()} locale="fr-FR" timeZone="Europe/Paris" />
 ```
 
 ---
@@ -219,5 +222,8 @@ Animated bouncing dots with a text description of who is typing.
 - DateSeparator's default formatter shows "Today", "Yesterday", or "Mon DD" / "Mon DD, YYYY"
 
 ## Changes
+### Unreleased
+- **Added** `DateSeparator` gained `locale?: string` and `timeZone?: string` props — the default label previously always used `en-US` month names and the browser's local time zone.
+
 ### v0.29.0
 - **Added** Initial release — 7 chat primitives (MessageList, Message, SystemMessage, MessageInput, DateSeparator, UnreadSeparator, TypingIndicator)

package/docs/components/ui/color-swatch.md

@@ -23,7 +23,7 @@
 ## Composability
 - **Server-safe, decorative-only primitive.** Accepts any valid CSS color string — hex, rgb, oklch, hsl, named. Pure presentation, no context.
 - **Usage patterns:** Inline color marker next to a label, preview dot in lists, color-indicator in a category chip, legend swatch for charts.
-- **`ring={true}`** adds a subtle outline — essential for white/very-light colors that would otherwise disappear on surface-raised backgrounds.
+- **`ring={true}`** adds a subtle outline — essential for white/very-light colors that would otherwise disappear on surface-panel backgrounds.
 - **Interactive color picking:** Use ColorInput (which opens a full picker). ColorSwatch is display-only.
 - No IconProvider cascade, no FormField consumption — composes freely with anything.
 

package/docs/components/ui/data-table-toolbar.md

@@ -11,10 +11,11 @@
     onGlobalFilterChange: (value: string) => void
     density: 'compact' | 'standard' | 'comfortable'
     onDensityChange: (density: Density) => void
-    enableExport: boolean
+    enableExport: boolean — show the Export CSV button (default true)
+    onExport: (visibleRows: TData[]) => void — replaces the built-in CSV logic; receives the currently visible filtered rows
 
 ## Defaults
-    none
+    enableExport=true, globalFilter=false
 
 ## Example
 ```jsx
@@ -44,6 +45,9 @@ import { DataTableToolbar } from '@devalok/shilp-sutra/ui/data-table-toolbar'
 - Prefer DataTable's `toolbar={true}` prop over rendering this directly
 
 ## Changes
+### v0.57.0
+- **Added** `onExport?: (visibleRows: TData[]) => void` — when provided, replaces the built-in CSV logic. Same signature as `DataTable`'s `onExport`, so the prop forwards straight through.
+
 ### v0.5.0
 - **Changed** (BREAKING) Removed from `@devalok/shilp-sutra/ui` barrel export — must use `@devalok/shilp-sutra/ui/data-table-toolbar`
 

package/docs/components/ui/data-table.md

@@ -5,20 +5,23 @@
 - Category: ui
 
 ## Props
-    columns: ColumnDef<TData>[] (TanStack column definitions)
+    columns: ColumnDef<TData, TValue>[] (TanStack column definitions)
     data: TData[]
+    className: string — class name for the wrapper div
     sortable: boolean — enable column sorting
-    onSort: (key: string, dir: 'asc' | 'desc' | false) => void — server-side sort callback (enables manualSorting)
+    onSort: (key: string, direction: 'asc' | 'desc' | false) => void — server-side sort callback (enables manualSorting)
     filterable: boolean — enable per-column filters
+    filterableColumns: string[] — restrict filter inputs to these column IDs (only with filterable; omit for all filterable columns)
     globalFilter: boolean — enable global search
     paginated: boolean — enable client-side pagination
     pagination: { page: number, pageSize: number, total: number, onPageChange: (page: number) => void } — server-side pagination (1-based page)
     pageSize: number (default 10)
+    pageSizeOptions: number[] — page-size selector options (default [10, 20, 50, 100])
     selectable: boolean — enable row selection with checkboxes
     selectedIds: Set<string> — controlled selection state
     selectableFilter: (row: TData) => boolean — disable selection on certain rows
     getRowId: (row: TData) => string — custom row ID accessor
-    onSelectionChange: (selectedRows: TData[]) => void
+    onSelectionChange: (selectedRows: TData[], selectedIds: Set<string>) => void — does NOT fire on mount
     expandable: boolean — enable row expansion
     renderExpanded: (row: TData) => ReactNode — expanded row content
     singleExpand: boolean — only one row expanded at a time
@@ -27,15 +30,23 @@
     noResultsText: string (default "No results.")
     stickyHeader: boolean — sticky table header
     onRowClick: (row: TData) => void — row click handler (excludes interactive element clicks)
-    bulkActions: BulkAction<TData>[] — floating action bar on selection — { label, onClick, color?: 'default'|'error', disabled? }
+    rowClassName: (row: TData) => string | undefined — conditional per-row class (the <tr> in table mode, the Card in card mode)
+    bulkActions: BulkAction<TData>[] — floating action bar on selection — { label, onClick, icon?: IconInput, color?: 'accent'|'error', disabled? }
+    bulkActionsPosition: 'bottom' | 'top' | 'inline' — where the bulk-actions bar renders (default 'bottom')
     toolbar: boolean — show DataTableToolbar (column visibility, density, CSV export)
+    enableExport: boolean — show the toolbar's Export CSV button (default true)
+    onExport: (visibleRows: TData[]) => void — replace the built-in CSV export
     editable: boolean — enable double-click cell editing
+    onCellEdit: (rowIndex: number, columnId: string, value: unknown) => void — fired on cell edit commit
     virtualRows: boolean — virtualize rows for large datasets
+    virtualRowHeight: number — ESTIMATED row height in px (default 48); real heights are measured after mount
+    maxHeight: number — max height of the virtual scroll container in px (default 600)
+    mobileView: 'card' | 'table' — stacked cards below the sm breakpoint (default 'table')
     columnPinning: { left?: string[], right?: string[] }
     density: 'compact' | 'standard' | 'comfortable'
 
 ## Defaults
-    pageSize=10, noResultsText="No results."
+    pageSize=10, noResultsText="No results.", enableExport=true, mobileView='table', virtualRowHeight=48, maxHeight=600, density='standard'
 
 ## Example
 ```jsx
@@ -75,7 +86,11 @@ import { DataTable } from '@devalok/shilp-sutra/ui/data-table'
 **Row click model:**
 - `onRowClick` fires on row-level click BUT excludes clicks on checkboxes, buttons, links, and inputs automatically. No manual `stopPropagation` needed for standard interactive elements.
 
-**Virtualization:** `virtualRows={true}` enables row virtualization via `@tanstack/react-virtual`. Turn it on for 1000+ row datasets; the scroll container must have a bounded height.
+**Virtualization:** `virtualRows={true}` enables row virtualization via `@tanstack/react-virtual`. Turn it on for 1000+ row datasets; the scroll container must have a bounded height. Rows stay in normal table flow (each windowed row is its own `<tbody>` measured by the virtualizer, with spacer row groups reserving the un-rendered remainder), so column widths keep tracking `<thead>` and `virtualRowHeight` is only the pre-measurement estimate.
+
+**Virtualization + expansion:** `virtualRows` and `expandable` compose. Because each row group is measured, an expanded detail panel of any height contributes to the total scroll size and pushes the rows below it down. The reveal is instant in virtual mode (no height animation) — an animating height would fire a resize on every frame.
+
+**Toolbar export:** the Export button renders whenever `toolbar` is on. The built-in CSV export walks `getFilteredRowModel()`, which under server-side `pagination` is only the current page — pass `onExport` to fetch the full set yourself, or `enableExport={false}` to drop the button.
 
 **Density integration:** density is forwarded to `Table`'s `density` prop, which sets `--table-py` (compact 4 / standard 8 / comfortable 12px → rows ≈ 29 / 37 / 45px; header tracks it). DataTableToolbar's density switcher updates this at runtime; the prop sets the initial state only.
 
@@ -88,13 +103,32 @@ import { DataTable } from '@devalok/shilp-sutra/ui/data-table'
 - onRowClick does NOT fire when clicking checkboxes, buttons, links, or inputs
 - Use density="compact" for Karm-style h-9 rows
 - `virtualRows={true}` requires a bounded scroll container — unbounded height silently disables virtualization
+- `onSelectionChange` does NOT fire on mount, and does NOT fire when selection is synced from the `selectedIds` prop — only on genuine selection changes
+- `filterableColumns` is ignored unless `filterable` is also set
+- `rowClassName` returns are passed through `cn()` verbatim — a class that does not exist in the token set silently does nothing (use the real scale steps, e.g. `bg-error-3`, not invented names like `bg-error-subtle`)
 
 ## Changes
+### Unreleased
+- **Added** `bulkActions[].icon?: IconInput` — icon rendered before the label in a bulk-action button.
+- **Added** `bulkActionsPosition?: 'bottom' | 'top' | 'inline'` — where the bulk-actions bar renders (default `'bottom'`, matching prior behavior).
+
+### v0.57.0
+- **Fixed** `onSelectionChange` no longer fires on mount with `[]` — first-render guard added. Root cause of the cascade reported in #213.
+- **Fixed** `virtualRows + expandable` was a silent no-op — the expanded row was only rendered on the non-virtual path. Virtual rows now render one measured `<tbody>` per windowed row (with spacer row groups for the remainder) so the expanded panel renders, contributes its real height to `getTotalSize()`, and cannot overlap the row below.
+- **Changed** Virtual rows are no longer absolutely positioned with a forced `virtualRowHeight`; they sit in normal table flow at their measured height, so column widths track `<thead>`. `virtualRowHeight` is now the pre-measurement ESTIMATE.
+- **Fixed** `enableExport` was stranded on `DataTableToolbar` and never wired through `DataTableProps`. Now exposed with an `onExport` override. Default is unchanged (`true`) — the Export button still renders whenever `toolbar` is on.
+- **Fixed** `filterable + mobileView="card"` rendered no filter inputs — they now render above the card list in `DataTableCards` (card mode renders no `<thead>` for them to live in).
+- **Added** `onSelectionChange` receives `selectedIds: Set<string>` as second argument — complement of the `selectedIds` prop.
+- **Added** `filterableColumns?: string[]` — restrict filter inputs to specific column IDs.
+- **Added** `rowClassName?: (row: TData) => string | undefined` — conditional row classes in table and card layouts.
+- **Added** `enableExport?: boolean` — hide the toolbar's Export CSV button from `DataTableProps`.
+- **Added** `onExport?: (visibleRows: TData[]) => void` — override built-in CSV with a custom export handler.
+
 ### v0.45.0
 - **Fixed** Expander a11y per the expando-row spec: `aria-expanded` on the toggle button, visually-hidden "Expand rows" column header; chevron rotation uses `duration-fast-02 ease-productive-standard`.
 - **Added** Expanded-row content animates open/closed (height + opacity via framer, `springs.smooth`), self-guarded with `useReducedMotion` — instant swap for reduced-motion users. Virtualized tables keep the instant reveal (a height animation would fight the virtualizer's measurements).
 - **Changed** Density now drives Table's `--table-py` variable (rows ≈ 29 / 37 / 45px; was 29 / 53 / 85). Per-cell `cellPadding` threading removed from context.
-- **Fixed** Hover/selected states visible on cards: row/sort-button/expander hover use `surface-raised-hover` (was the invisible `surface-raised`); expanded row is a `surface-base` recess; sticky header bg is `surface-raised`; empty state uses `py-ds-07` (was raw `h-24`).
+- **Fixed** Hover/selected states visible on cards: row/sort-button/expander hover use `surface-panel-hover` (was the invisible `surface-panel`); expanded row is a `surface-base` recess; sticky header bg is `surface-panel`; empty state uses `py-ds-07` (was raw `h-24`).
 - **Changed** Mobile card view composes `<Card size="sm" variant="outline">` (was a hand-rolled 12px bordered box).
 
 ### v0.29.0

package/docs/components/ui/dot.md

@@ -49,7 +49,7 @@ sized, optionally pulsing, filled or ring.
 - **`pulse` = "live".** Off by default (static status). Turn it on for active/attention states (recording, live, connecting) — a pulsing dot reads as "happening now", so leave it off for settled statuses.
 - **Powers the higher-level pieces.** `StatusBadge` composes `<Badge>` + `<Dot>`; use `Dot` directly anywhere you need a coloured indicator without a pill.
 - **Three treatments:** `filled` (active), `ring` (hollow outline), `off` (faint same-tone fill + light border — present but inactive/disabled).
-- **`withBorder`** adds a contrast ring (`ring-2 ring-surface-raised`) so the dot reads on avatars, images, or coloured fills — the pattern Avatar's status dot uses.
+- **`withBorder`** adds a contrast ring (`ring-2 ring-surface-panel`) so the dot reads on avatars, images, or coloured fills — the pattern Avatar's status dot uses.
 - **`pulseSpeed`** (slow/normal/fast) tunes the pulse tempo — fast for urgent (recording), slow for ambient (syncing).
 
 ## Gotchas

package/docs/components/ui/progress.md

@@ -66,6 +66,7 @@ common cases, or the compound parts (`Progress.Root` / `Track` / `Indicator` /
 - Omit `value` (or pass `null`) for indeterminate.
 - Pass an explicit `color` to override `autoColor`.
 - Compound `Progress.Track` needs a name — an `aria-label`, or a `Progress.Label` whose `id` the Track's `aria-labelledby` points to. A Track with neither is an unnamed progressbar (axe will flag it).
+- **`<Progress value={72} />` with no name warns in DEV.** `aria-valuenow` already carries the number, so an unnamed bar announces as "progressbar, 72%" — the reader learns the value but not *what* is progressing. Pass `label` (renders visible text and wires `aria-labelledby`) or `aria-label` when the bar must stay visually unlabelled. The component deliberately does **not** invent a default like "Progress: 72%": that would silence the audit while leaving the announcement equally uninformative, and only you know what the bar measures. Warns once per session, not per render.
 - `Progress.Indicator` / `Segment` / `Value` throw if rendered outside `Progress.Root`.
 
 ## Changes

package/docs/components/ui/surface.md

@@ -18,8 +18,8 @@ The low-level elevated container primitive. Owns background + shadow + radius +
     Surface: elevation="raised", padding="none", radius="surface", bordered=false
 
 ## Elevation
-    flat      — bg-surface-raised, no shadow (pair with `bordered` for an on-page tile)
-    raised    — bg-surface-raised + shadow-raised (card level)
+    flat      — bg-surface-panel, no shadow (pair with `bordered` for an on-page tile)
+    raised    — bg-surface-panel + shadow-raised (card level)
     floating  — bg-surface-overlay + shadow-floating (toasts, floating toolbars)
     overlay   — bg-surface-overlay + shadow-overlay (popovers, menus, dialogs)
 
@@ -48,7 +48,7 @@ The low-level elevated container primitive. Owns background + shadow + radius +
 
 ## Gotchas
 - **Edge OR elevation, never both.** Combining `bordered` with a shadowed elevation (raised/floating/overlay) is the double-edge anti-pattern and dev-warns. Use `elevation="flat"` with `bordered`, or drop `bordered` and let the shadow be the edge.
-- `flat` still uses `bg-surface-raised` (a card without a shadow), not the page background — it is a surface, not a hole.
+- `flat` still uses `bg-surface-panel` (a card without a shadow), not the page background — it is a surface, not a hole.
 
 ## Changes
 ### Unreleased

package/docs/components/ui/table.md

@@ -106,12 +106,12 @@ See the `RichCells` story for all of these live.
 - **Added** `TableRowLink` (ui/table-row-link) — real-anchor whole-row navigation with pseudo-element stretch (Safari-safe: anchored to the cell, clipped by the table's `overflow-x-clip`), row-level focus ring, `stretch={false}` title-only mode.
 - **Added** `TableRowActions` — hover/focus-revealed action cluster (opacity reveal, permanently tabbable, `:focus-within` + touch fallbacks, `persist` mode).
 - **Added** `numeric` prop on TableCell/TableHead — right-align + tabular figures.
-- **Fixed** TableFooter background was `color-mix(surface-raised 50%)` — invisible on cards (same mis-mapped shadcn `muted/50` family as the row hover). Now a `surface-base` band with a top hairline.
+- **Fixed** TableFooter background was `color-mix(surface-panel 50%)` — invisible on cards (same mis-mapped shadcn `muted/50` family as the row hover). Now a `surface-base` band with a top hairline.
 - **Fixed** Selected+hover tie: selected rows get an explicit `hover:bg-accent-4` step (hover and selected previously tied on specificity).
 - **Added** Cell recipes section (user cell, tag overflow, money, empty-dash) + density→avatar mapping; `RichCells` / `SelectedRows` stories.
 - **Added** `density` prop (`compact | standard | comfortable`) via `--table-py`; header height tracks density instead of a fixed 40px
 - **Added** `striped` prop — opt-in zebra
-- **Changed** Rows regain their hairline separator (`border-b border-surface-border-subtle` — lost in the original port) and hover becomes visible on cards (`hover:bg-surface-raised-hover`, was the invisible `surface-raised`)
+- **Changed** Rows regain their hairline separator (`border-b border-surface-border-subtle` — lost in the original port) and hover becomes visible on cards (`hover:bg-surface-panel-hover`, was the invisible `surface-panel`)
 - **Changed** Cells: `px-ds-04` interior, first/last cells read `--table-edge` (= `--card-spacing` inside a Card); header drops to `text-ds-sm` muted
 - **Changed** Default vertical rhythm tightens: standard rows ~53px → ~37px
 

package/docs/recipes/install-astro.md

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

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

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

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

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

@@ -194,17 +194,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)
 

package/llms.txt

@@ -1,6 +1,6 @@
 # @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).
 
@@ -152,6 +152,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/make-kit/Guidelines.md

@@ -22,10 +22,10 @@
 These are not preferences. Generated code that violates them is wrong.
 
 1. **Use design system components, not raw HTML.** `<Button>` not `<button>`. `<Input>` not `<input>`. `<Text>` not `<span>`/`<p>` (when typographic semantics matter). `<Stack>` not bare flex divs.
-2. **Use semantic tokens, never hex / rgb / hsl.** `bg-surface-raised` not `bg-white`. `text-fg` not `text-zinc-900`. `bg-accent-9` not `bg-pink-500`.
+2. **Use semantic tokens, never hex / rgb / hsl.** `bg-surface-panel` not `bg-white`. `text-fg` not `text-zinc-900`. `bg-accent-9` not `bg-pink-500`.
 3. **Spacing uses `ds-*` cadence.** `p-ds-05`, `gap-ds-03`. Never `p-4` / `p-6`. Default cadence is `ds-03 / ds-05 / ds-07` (related items / grouped sections / page sections). Do not reach for every adjacent token (`ds-04`, `ds-06`) — three tiers, not five.
 4. **Prefer `variant="soft"` over `variant="outline"` for non-primary actions.** Soft (tinted bg, no visible border) reads better in data-dense UIs. Outline only when on a colored bg or paired with a primary for explicit hierarchy.
-5. **Surface layering is strict.** Page = `surface-base`. Cards/panels/widgets = `surface-raised`. Dialogs/popovers/dropdowns/inputs = `surface-overlay`. Shell chrome (sidebar, topbar) = `surface-sunken`. Tooltips = `surface-inverted`. If you're unsure, read `foundations/surfaces.md`.
+5. **Surface layering is strict.** Page = `surface-base`. Cards/panels/widgets = `surface-panel`. Dialogs/popovers/dropdowns/inputs = `surface-overlay`. Shell chrome (sidebar, topbar) = `surface-sunken`. Tooltips = `surface-inverted`. If you're unsure, read `foundations/surfaces.md`.
 6. **Never combine `border-*` + `shadow-*` tokens.** Shadow tokens already include a 1px ring layer. Adding an explicit border creates a 2-px edge.
 7. **Icons use `<Icon icon={...} />` from `@tabler/icons-react`.** Do not import lucide, heroicons, mui-icons. The icon system auto-sizes via `IconProvider` context.
 8. **Toasts mount once at app root.** `<Toaster />` (singleton). All triggering is imperative: `toast.success("...")`, `toast.error("...")`.

package/make-kit/components/button.md

@@ -19,7 +19,7 @@ import { Button } from '@devalok/shilp-sutra/ui/button'
 |---|---|
 | `solid` (default) | Primary CTA. One per region. Heavy visual weight. |
 | `soft` | Secondary action. **Preferred default for any non-primary action.** Tinted bg, colored text, no visible border — warmer than outline, brand-consistent. |
-| `outline` | Secondary action on a colored / `surface-raised` bg where soft's tint disappears. In toolbars / icon-dense rows. Paired adjacent to a primary that needs explicit hierarchy. |
+| `outline` | Secondary action on a colored / `surface-panel` bg where soft's tint disappears. In toolbars / icon-dense rows. Paired adjacent to a primary that needs explicit hierarchy. |
 | `ghost` | Tertiary / dismissive — close, cancel, skip. Minimal weight. |
 | `link` | Inline action that should read as a link but behave as a button. Use sparingly. |
 

package/make-kit/components/card.md

@@ -20,18 +20,18 @@ import {
 
 - Any rectangular region that reads as a discrete unit on the page: dashboards widgets, list items, marketing feature blocks.
 - Header / actions / footer are built in as slots (`CardHeader`, `CardAction`, `CardFooter`) — don't reach for a wrapper. (`<ContentCard>` is deprecated; use Card slots.)
-- Need just a tinted region with no card affordance? Use a `<div className="bg-surface-raised">` (rare; usually Card is right).
+- Need just a tinted region with no card affordance? Use a `<div className="bg-surface-panel">` (rare; usually Card is right).
 
-Card renders on `surface-raised`. The `default` variant is tonal — a surface-tone shift plus a whisper hairline (`border-card`), no shadow. **Never** override its background or border.
+Card renders on `surface-panel`. The `default` variant is tonal — a surface-tone shift plus a whisper hairline (`border-card`), no shadow. **Never** override its background or border.
 
 ## Variants
 
 | Variant | Use |
 |---|---|
-| `default` (default) | `surface-raised` + tonal `border-card` hairline, no shadow. Standard card — depth from tone, not a drop shadow. |
+| `default` (default) | `surface-panel` + tonal `border-card` hairline, no shadow. Standard card — depth from tone, not a drop shadow. |
 | `elevated` | `shadow-raised-hover`, no border. Use when a card must visibly pop (hero, dragged tile, spotlight panel). |
-| `outline` | `surface-raised` + strong border-only (no shadow). Dense lists where stacked shadowed cards would feel too lifted. |
-| `flat` | `surface-raised` + no shadow, no border. For cards inside an already-elevated container. |
+| `outline` | `surface-panel` + strong border-only (no shadow). Dense lists where stacked shadowed cards would feel too lifted. |
+| `flat` | `surface-panel` + no shadow, no border. For cards inside an already-elevated container. |
 
 ## Colors
 
@@ -186,7 +186,7 @@ wrap the text column in `<CardSection>`, which re-establishes py + gap from the
 
 ## Rules
 
-- **Never** `bg-surface-base` on a Card — cards sit on `surface-raised`. The pre-publish audit rejects this.
+- **Never** `bg-surface-base` on a Card — cards sit on `surface-panel`. The pre-publish audit rejects this.
 - **Never** combine `border-*` + `shadow-*` on a Card. Pick one (Card already does — don't override).
 - **Use `interactive` + `onClick` + `aria-label`** for clickable cards. Don't wrap a Card in a `<button>` — broken nesting.
 - **`size` on Card** drives all spacing via `--card-spacing`. Never set `p-*` on Card or a slot — override the variable if a one-off is truly needed.

package/make-kit/components/surface.md

@@ -9,7 +9,7 @@ The low-level elevated container. It paints a tokened surface — background + s
 ## When to use
 
 - You need a plain elevated box (a promo, a callout, a small panel) and don't need Card's header/content/footer slots.
-- You're building a new component that sits on a surface — compose `Surface`, never hand-roll `bg-surface-raised … shadow-raised`.
+- You're building a new component that sits on a surface — compose `Surface`, never hand-roll `bg-surface-panel … shadow-raised`.
 
 Use `<Card>` instead when you want the gap-model padding rhythm and the `CardHeader`/`CardContent`/`CardFooter` slots. Use raw utilities for nothing — if it's a surface, it's a `Surface`.
 
@@ -17,8 +17,8 @@ Use `<Card>` instead when you want the gap-model padding rhythm and the `CardHea
 
 | `elevation` | Surface | Use for |
 |---|---|---|
-| `flat` | `bg-surface-raised`, no shadow | On-page tiles. Pair with `bordered` for an edge. |
-| `raised` *(default)* | `bg-surface-raised` + `shadow-raised` | Cards, panels — anything sitting on the page. |
+| `flat` | `bg-surface-panel`, no shadow | On-page tiles. Pair with `bordered` for an edge. |
+| `raised` *(default)* | `bg-surface-panel` + `shadow-raised` | Cards, panels — anything sitting on the page. |
 | `floating` | `bg-surface-overlay` + `shadow-floating` | Toasts, floating toolbars. |
 | `overlay` | `bg-surface-overlay` + `shadow-overlay` | Popovers, menus, dialogs. |
 
@@ -55,6 +55,6 @@ Plus all native `div` props. Server-safe; forwards ref.
 ## Rules
 
 - **Edge OR elevation, never both.** `bordered` + a shadowed `elevation` is the double-edge anti-pattern (dev-warns). Use `elevation="flat" bordered`, or drop `bordered`.
-- `flat` is still a surface (`bg-surface-raised`), not the page — a card without a shadow, not a hole in the page.
+- `flat` is still a surface (`bg-surface-panel`), not the page — a card without a shadow, not a hole in the page.
 - Don't reach for `Surface` when you mean `Card` — if you're rebuilding header/content/footer spacing by hand, use `Card`.
 - Padding is symmetric. For anything asymmetric, use `className` or `Card`.