@devalok/shilp-sutra 0.48.0 → 0.49.1

package/dist/ui/tooltip.js

@@ -1,62 +1,65 @@
 "use client";
-import { F as e, M as t, N as n, P as r, j as i } from "../_chunks/primitives.js";
+import { Content2$1 as e, Portal as t, Provider as n, Root3$1 as r, Trigger$3 as i } from "../_chunks/primitives.js";
 import { springs as a, tweens as o } from "./lib/motion.js";
 import { cn as s } from "./lib/utils.js";
-import * as c from "react";
-import { Fragment as l, jsx as u } from "react/jsx-runtime";
-import { AnimatePresence as d, motion as f } from "framer-motion";
+import { useControllableOpen as c } from "../_chunks/use-controllable-open.js";
+import * as l from "react";
+import { Fragment as u, jsx as d } from "react/jsx-runtime";
+import { AnimatePresence as f, motion as p } from "framer-motion";
 //#region src/ui/tooltip.tsx
-var p = c.createContext(!1), m = ({ children: e, ...t }) => /* @__PURE__ */ u(p.Provider, {
+var m = l.createContext(!1), h = ({ children: e, ...t }) => /* @__PURE__ */ d(m.Provider, {
 	value: !0,
-	children: /* @__PURE__ */ u(n, {
+	children: /* @__PURE__ */ d(n, {
 		...t,
 		children: e
 	})
 });
-function h({ children: e }) {
-	return c.useContext(p) ? /* @__PURE__ */ u(l, { children: e }) : /* @__PURE__ */ u(p.Provider, {
+function g({ children: e }) {
+	return l.useContext(m) ? /* @__PURE__ */ d(u, { children: e }) : /* @__PURE__ */ d(m.Provider, {
 		value: !0,
-		children: /* @__PURE__ */ u(n, {
+		children: /* @__PURE__ */ d(n, {
 			delayDuration: 300,
 			children: e
 		})
 	});
 }
-var g = c.createContext({ open: !1 }), _ = ({ open: e, defaultOpen: t, onOpenChange: n, ...i }) => {
-	let [a, o] = c.useState(t ?? !1), s = e !== void 0, l = s ? e : a, d = c.useCallback((e) => {
-		s || o(e), n?.(e);
-	}, [s, n]), f = c.useMemo(() => ({ open: l }), [l]);
-	return /* @__PURE__ */ u(h, { children: /* @__PURE__ */ u(g.Provider, {
-		value: f,
-		children: /* @__PURE__ */ u(r, {
-			open: l,
-			onOpenChange: d,
+var _ = l.createContext({ open: !1 }), v = ({ open: e, defaultOpen: t, onOpenChange: n, ...i }) => {
+	let { open: a, setOpen: o } = c({
+		open: e,
+		defaultOpen: t,
+		onOpenChange: n
+	}), s = l.useMemo(() => ({ open: a }), [a]);
+	return /* @__PURE__ */ d(g, { children: /* @__PURE__ */ d(_.Provider, {
+		value: s,
+		children: /* @__PURE__ */ d(r, {
+			open: a,
+			onOpenChange: o,
 			...i
 		})
 	}) });
 };
-_.displayName = "Tooltip";
-var v = e, y = {
+v.displayName = "Tooltip";
+var y = i, b = {
 	top: { y: 4 },
 	bottom: { y: -4 },
 	left: { x: 4 },
 	right: { x: -4 }
-}, b = c.forwardRef(({ className: e, sideOffset: n = 4, side: r = "top", children: l, ...p }, m) => {
-	let { open: h } = c.useContext(g), _ = y[r] ?? {};
-	return /* @__PURE__ */ u(d, { children: h && /* @__PURE__ */ u(t, {
+}, x = l.forwardRef(({ className: n, sideOffset: r = 4, side: i = "top", children: c, ...u }, m) => {
+	let { open: h } = l.useContext(_), g = b[i] ?? {};
+	return /* @__PURE__ */ d(f, { children: h && /* @__PURE__ */ d(t, {
 		forceMount: !0,
-		children: /* @__PURE__ */ u(i, {
+		children: /* @__PURE__ */ d(e, {
 			ref: m,
 			forceMount: !0,
-			sideOffset: n,
-			side: r,
-			...p,
+			sideOffset: r,
+			side: i,
+			...u,
 			asChild: !0,
-			children: /* @__PURE__ */ u(f.div, {
+			children: /* @__PURE__ */ d(p.div, {
 				initial: {
 					opacity: 0,
 					scale: .95,
-					..._
+					...g
 				},
 				animate: {
 					opacity: 1,
@@ -67,18 +70,18 @@ var v = e, y = {
 				exit: {
 					opacity: 0,
 					scale: .95,
-					..._
+					...g
 				},
 				transition: {
 					...a.snappy,
 					opacity: o.fade
 				},
-				className: s("z-tooltip overflow-hidden rounded-overlay-sm bg-surface-inverted px-ds-04 py-ds-02b text-ds-sm text-surface-inverted-fg shadow-floating", e),
-				children: l
+				className: s("z-tooltip overflow-hidden rounded-overlay-sm bg-surface-inverted px-ds-04 py-ds-02b text-ds-sm text-surface-inverted-fg shadow-floating", n),
+				children: c
 			})
 		})
 	}) });
 });
-b.displayName = i.displayName;
+x.displayName = e.displayName;
 //#endregion
-export { _ as Tooltip, b as TooltipContent, m as TooltipProvider, v as TooltipTrigger };
+export { v as Tooltip, x as TooltipContent, h as TooltipProvider, y as TooltipTrigger };

package/dist/ui/tooltip.js.map

@@ -1 +1 @@
-{"version":3,"file":"tooltip.js","names":[],"sources":["../../src/ui/tooltip.tsx"],"sourcesContent":["'use client'\n\nimport * as TooltipPrimitive from '@primitives/react-tooltip'\nimport { AnimatePresence,motion } from 'framer-motion'\nimport * as React from 'react'\n\nimport { springs, tweens } from './lib/motion'\nimport { cn } from './lib/utils'\n\n// ── Auto-provider: wraps with TooltipPrimitive.Provider if none exists ──\n\nconst TooltipProviderContext = React.createContext(false)\n\nconst TooltipProvider: React.FC<React.ComponentPropsWithoutRef<typeof TooltipPrimitive.Provider>> = ({\n  children,\n  ...props\n}) => (\n  <TooltipProviderContext.Provider value={true}>\n    <TooltipPrimitive.Provider {...props}>\n      {children}\n    </TooltipPrimitive.Provider>\n  </TooltipProviderContext.Provider>\n)\n\nfunction AutoProvider({ children }: { children: React.ReactNode }) {\n  const hasProvider = React.useContext(TooltipProviderContext)\n  if (hasProvider) return <>{children}</>\n  return (\n    <TooltipProviderContext.Provider value={true}>\n      <TooltipPrimitive.Provider delayDuration={300}>\n        {children}\n      </TooltipPrimitive.Provider>\n    </TooltipProviderContext.Provider>\n  )\n}\n\n// ── Internal context to thread `open` state to animated children ──\n\ntype TooltipContextValue = { open: boolean }\nconst TooltipContext = React.createContext<TooltipContextValue>({ open: false })\n\nconst Tooltip: React.FC<React.ComponentPropsWithoutRef<typeof TooltipPrimitive.Root>> = ({\n  open: openProp,\n  defaultOpen,\n  onOpenChange,\n  ...props\n}) => {\n  const [internalOpen, setInternalOpen] = React.useState(defaultOpen ?? false)\n  const isControlled = openProp !== undefined\n  const open = isControlled ? openProp : internalOpen\n\n  const handleOpenChange = React.useCallback(\n    (nextOpen: boolean) => {\n      if (!isControlled) setInternalOpen(nextOpen)\n      onOpenChange?.(nextOpen)\n    },\n    [isControlled, onOpenChange],\n  )\n\n  const contextValue = React.useMemo(() => ({ open }), [open])\n\n  return (\n    <AutoProvider>\n      <TooltipContext.Provider value={contextValue}>\n        <TooltipPrimitive.Root open={open} onOpenChange={handleOpenChange} {...props} />\n      </TooltipContext.Provider>\n    </AutoProvider>\n  )\n}\nTooltip.displayName = 'Tooltip'\n\nconst TooltipTrigger = TooltipPrimitive.Trigger\n\n// ── Side-based slide offsets ──\n\nconst sideOffset: Record<string, { x?: number; y?: number }> = {\n  top: { y: 4 },\n  bottom: { y: -4 },\n  left: { x: 4 },\n  right: { x: -4 },\n}\n\nconst TooltipContent = React.forwardRef<\n  React.ElementRef<typeof TooltipPrimitive.Content>,\n  React.ComponentPropsWithoutRef<typeof TooltipPrimitive.Content>\n>(({ className, sideOffset: sideOffsetProp = 4, side = 'top', children, ...props }, ref) => {\n  const { open } = React.useContext(TooltipContext)\n  const slideInit = sideOffset[side] ?? {}\n\n  return (\n    <AnimatePresence>\n      {open && (\n        <TooltipPrimitive.Portal forceMount>\n          <TooltipPrimitive.Content\n            ref={ref}\n            forceMount\n            sideOffset={sideOffsetProp}\n            side={side}\n            {...props}\n            asChild\n          >\n            <motion.div\n              initial={{ opacity: 0, scale: 0.95, ...slideInit }}\n              animate={{ opacity: 1, scale: 1, x: 0, y: 0 }}\n              exit={{ opacity: 0, scale: 0.95, ...slideInit }}\n              transition={{ ...springs.snappy, opacity: tweens.fade }}\n              className={cn(\n                'z-tooltip overflow-hidden rounded-overlay-sm bg-surface-inverted px-ds-04 py-ds-02b text-ds-sm text-surface-inverted-fg shadow-floating',\n                className,\n              )}\n            >\n              {children}\n            </motion.div>\n          </TooltipPrimitive.Content>\n        </TooltipPrimitive.Portal>\n      )}\n    </AnimatePresence>\n  )\n})\nTooltipContent.displayName = TooltipPrimitive.Content.displayName\n\nexport type TooltipContentProps = React.ComponentPropsWithoutRef<typeof TooltipPrimitive.Content>\n\nexport { Tooltip, TooltipContent, TooltipProvider,TooltipTrigger }\n"],"mappings":";;;;;;;;AAWA,IAAM,IAAyB,EAAM,cAAc,GAAM,EAEnD,KAA+F,EACnG,aACA,GAAG,QAEH,kBAAC,EAAuB,UAAxB;CAAiC,OAAO;WACtC,kBAAC,GAAD;EAA2B,GAAI;EAC5B;EACyB,CAAA;CACI,CAAA;AAGpC,SAAS,EAAa,EAAE,eAA2C;AAGjE,QAFoB,EAAM,WAAW,EAAuB,GACpC,kBAAA,GAAA,EAAG,aAAY,CAAA,GAErC,kBAAC,EAAuB,UAAxB;EAAiC,OAAO;YACtC,kBAAC,GAAD;GAA2B,eAAe;GACvC;GACyB,CAAA;EACI,CAAA;;AAOtC,IAAM,IAAiB,EAAM,cAAmC,EAAE,MAAM,IAAO,CAAC,EAE1E,KAAmF,EACvF,MAAM,GACN,gBACA,iBACA,GAAG,QACC;CACJ,IAAM,CAAC,GAAc,KAAmB,EAAM,SAAS,KAAe,GAAM,EACtE,IAAe,MAAa,KAAA,GAC5B,IAAO,IAAe,IAAW,GAEjC,IAAmB,EAAM,aAC5B,MAAsB;AAErB,EADK,KAAc,EAAgB,EAAS,EAC5C,IAAe,EAAS;IAE1B,CAAC,GAAc,EAAa,CAC7B,EAEK,IAAe,EAAM,eAAe,EAAE,SAAM,GAAG,CAAC,EAAK,CAAC;AAE5D,QACE,kBAAC,GAAD,EAAA,UACE,kBAAC,EAAe,UAAhB;EAAyB,OAAO;YAC9B,kBAAC,GAAD;GAA6B;GAAM,cAAc;GAAkB,GAAI;GAAS,CAAA;EACxD,CAAA,EACb,CAAA;;AAGnB,EAAQ,cAAc;AAEtB,IAAM,IAAiB,GAIjB,IAAyD;CAC7D,KAAK,EAAE,GAAG,GAAG;CACb,QAAQ,EAAE,GAAG,IAAI;CACjB,MAAM,EAAE,GAAG,GAAG;CACd,OAAO,EAAE,GAAG,IAAI;CACjB,EAEK,IAAiB,EAAM,YAG1B,EAAE,cAAW,YAAY,IAAiB,GAAG,UAAO,OAAO,aAAU,GAAG,KAAS,MAAQ;CAC1F,IAAM,EAAE,YAAS,EAAM,WAAW,EAAe,EAC3C,IAAY,EAAW,MAAS,EAAE;AAExC,QACE,kBAAC,GAAD,EAAA,UACG,KACC,kBAAC,GAAD;EAAyB,YAAA;YACvB,kBAAC,GAAD;GACO;GACL,YAAA;GACA,YAAY;GACN;GACN,GAAI;GACJ,SAAA;aAEA,kBAAC,EAAO,KAAR;IACE,SAAS;KAAE,SAAS;KAAG,OAAO;KAAM,GAAG;KAAW;IAClD,SAAS;KAAE,SAAS;KAAG,OAAO;KAAG,GAAG;KAAG,GAAG;KAAG;IAC7C,MAAM;KAAE,SAAS;KAAG,OAAO;KAAM,GAAG;KAAW;IAC/C,YAAY;KAAE,GAAG,EAAQ;KAAQ,SAAS,EAAO;KAAM;IACvD,WAAW,EACT,2IACA,EACD;IAEA;IACU,CAAA;GACY,CAAA;EACH,CAAA,EAEZ,CAAA;EAEpB;AACF,EAAe,cAAA,EAAuC"}
+{"version":3,"file":"tooltip.js","names":[],"sources":["../../src/ui/tooltip.tsx"],"sourcesContent":["'use client'\n\nimport * as TooltipPrimitive from '@primitives/react-tooltip'\nimport { AnimatePresence,motion } from 'framer-motion'\nimport * as React from 'react'\n\nimport { springs, tweens } from './lib/motion'\nimport { useControllableOpen } from './lib/use-controllable-open'\nimport { cn } from './lib/utils'\n\n// ── Auto-provider: wraps with TooltipPrimitive.Provider if none exists ──\n\nconst TooltipProviderContext = React.createContext(false)\n\nconst TooltipProvider: React.FC<React.ComponentPropsWithoutRef<typeof TooltipPrimitive.Provider>> = ({\n  children,\n  ...props\n}) => (\n  <TooltipProviderContext.Provider value={true}>\n    <TooltipPrimitive.Provider {...props}>\n      {children}\n    </TooltipPrimitive.Provider>\n  </TooltipProviderContext.Provider>\n)\n\nfunction AutoProvider({ children }: { children: React.ReactNode }) {\n  const hasProvider = React.useContext(TooltipProviderContext)\n  if (hasProvider) return <>{children}</>\n  return (\n    <TooltipProviderContext.Provider value={true}>\n      <TooltipPrimitive.Provider delayDuration={300}>\n        {children}\n      </TooltipPrimitive.Provider>\n    </TooltipProviderContext.Provider>\n  )\n}\n\n// ── Internal context to thread `open` state to animated children ──\n\ntype TooltipContextValue = { open: boolean }\nconst TooltipContext = React.createContext<TooltipContextValue>({ open: false })\n\nconst Tooltip: React.FC<React.ComponentPropsWithoutRef<typeof TooltipPrimitive.Root>> = ({\n  open: openProp,\n  defaultOpen,\n  onOpenChange,\n  ...props\n}) => {\n  const { open, setOpen } = useControllableOpen({ open: openProp, defaultOpen, onOpenChange })\n\n  const contextValue = React.useMemo(() => ({ open }), [open])\n\n  return (\n    <AutoProvider>\n      <TooltipContext.Provider value={contextValue}>\n        <TooltipPrimitive.Root open={open} onOpenChange={setOpen} {...props} />\n      </TooltipContext.Provider>\n    </AutoProvider>\n  )\n}\nTooltip.displayName = 'Tooltip'\n\nconst TooltipTrigger = TooltipPrimitive.Trigger\n\n// ── Side-based slide offsets ──\n\nconst sideOffset: Record<string, { x?: number; y?: number }> = {\n  top: { y: 4 },\n  bottom: { y: -4 },\n  left: { x: 4 },\n  right: { x: -4 },\n}\n\nconst TooltipContent = React.forwardRef<\n  React.ElementRef<typeof TooltipPrimitive.Content>,\n  React.ComponentPropsWithoutRef<typeof TooltipPrimitive.Content>\n>(({ className, sideOffset: sideOffsetProp = 4, side = 'top', children, ...props }, ref) => {\n  const { open } = React.useContext(TooltipContext)\n  const slideInit = sideOffset[side] ?? {}\n\n  return (\n    <AnimatePresence>\n      {open && (\n        <TooltipPrimitive.Portal forceMount>\n          <TooltipPrimitive.Content\n            ref={ref}\n            forceMount\n            sideOffset={sideOffsetProp}\n            side={side}\n            {...props}\n            asChild\n          >\n            <motion.div\n              initial={{ opacity: 0, scale: 0.95, ...slideInit }}\n              animate={{ opacity: 1, scale: 1, x: 0, y: 0 }}\n              exit={{ opacity: 0, scale: 0.95, ...slideInit }}\n              transition={{ ...springs.snappy, opacity: tweens.fade }}\n              className={cn(\n                'z-tooltip overflow-hidden rounded-overlay-sm bg-surface-inverted px-ds-04 py-ds-02b text-ds-sm text-surface-inverted-fg shadow-floating',\n                className,\n              )}\n            >\n              {children}\n            </motion.div>\n          </TooltipPrimitive.Content>\n        </TooltipPrimitive.Portal>\n      )}\n    </AnimatePresence>\n  )\n})\nTooltipContent.displayName = TooltipPrimitive.Content.displayName\n\nexport type TooltipContentProps = React.ComponentPropsWithoutRef<typeof TooltipPrimitive.Content>\n\nexport { Tooltip, TooltipContent, TooltipProvider,TooltipTrigger }\n"],"mappings":";;;;;;;;;AAYA,IAAM,IAAyB,EAAM,cAAc,GAAM,EAEnD,KAA+F,EACnG,aACA,GAAG,QAEH,kBAAC,EAAuB,UAAxB;CAAiC,OAAO;WACtC,kBAAC,GAAD;EAA2B,GAAI;EAC5B;EACyB,CAAA;CACI,CAAA;AAGpC,SAAS,EAAa,EAAE,eAA2C;AAGjE,QAFoB,EAAM,WAAW,EAAuB,GACpC,kBAAA,GAAA,EAAG,aAAY,CAAA,GAErC,kBAAC,EAAuB,UAAxB;EAAiC,OAAO;YACtC,kBAAC,GAAD;GAA2B,eAAe;GACvC;GACyB,CAAA;EACI,CAAA;;AAOtC,IAAM,IAAiB,EAAM,cAAmC,EAAE,MAAM,IAAO,CAAC,EAE1E,KAAmF,EACvF,MAAM,GACN,gBACA,iBACA,GAAG,QACC;CACJ,IAAM,EAAE,SAAM,eAAY,EAAoB;EAAE,MAAM;EAAU;EAAa;EAAc,CAAC,EAEtF,IAAe,EAAM,eAAe,EAAE,SAAM,GAAG,CAAC,EAAK,CAAC;AAE5D,QACE,kBAAC,GAAD,EAAA,UACE,kBAAC,EAAe,UAAhB;EAAyB,OAAO;YAC9B,kBAAC,GAAD;GAA6B;GAAM,cAAc;GAAS,GAAI;GAAS,CAAA;EAC/C,CAAA,EACb,CAAA;;AAGnB,EAAQ,cAAc;AAEtB,IAAM,IAAiB,GAIjB,IAAyD;CAC7D,KAAK,EAAE,GAAG,GAAG;CACb,QAAQ,EAAE,GAAG,IAAI;CACjB,MAAM,EAAE,GAAG,GAAG;CACd,OAAO,EAAE,GAAG,IAAI;CACjB,EAEK,IAAiB,EAAM,YAG1B,EAAE,cAAW,YAAY,IAAiB,GAAG,UAAO,OAAO,aAAU,GAAG,KAAS,MAAQ;CAC1F,IAAM,EAAE,YAAS,EAAM,WAAW,EAAe,EAC3C,IAAY,EAAW,MAAS,EAAE;AAExC,QACE,kBAAC,GAAD,EAAA,UACG,KACC,kBAAC,GAAD;EAAyB,YAAA;YACvB,kBAAC,GAAD;GACO;GACL,YAAA;GACA,YAAY;GACN;GACN,GAAI;GACJ,SAAA;aAEA,kBAAC,EAAO,KAAR;IACE,SAAS;KAAE,SAAS;KAAG,OAAO;KAAM,GAAG;KAAW;IAClD,SAAS;KAAE,SAAS;KAAG,OAAO;KAAG,GAAG;KAAG,GAAG;KAAG;IAC7C,MAAM;KAAE,SAAS;KAAG,OAAO;KAAM,GAAG;KAAW;IAC/C,YAAY;KAAE,GAAG,EAAQ;KAAQ,SAAS,EAAO;KAAM;IACvD,WAAW,EACT,2IACA,EACD;IAEA;IACU,CAAA;GACY,CAAA;EACH,CAAA,EAEZ,CAAA;EAEpB;AACF,EAAe,cAAA,EAAuC"}

package/dist/ui/tree-view/index.js

@@ -1,3 +1,3 @@
 "use client";
-import { n as e, r as t, t as n } from "../../_chunks/tree-view.js";
-export { n as TreeItem, e as TreeView, t as useTree };
+import { TreeItem as e, TreeView as t, useTree as n } from "../../_chunks/tree-view.js";
+export { e as TreeItem, t as TreeView, n as useTree };

package/docs/components/ai/ai-command-provider.md

@@ -0,0 +1,46 @@
+# AICommandProvider
+
+- Import: @devalok/shilp-sutra/ai/ai-command-provider
+- Server-safe: No
+- Category: ai
+
+Context provider for the AI command system. Supplies custom block renderers, the
+action handler, and the agent identity to `AIConversation` / `BlockRenderer` below
+it, so you configure them once instead of threading props through every message.
+Ships a `useAICommand()` hook to read the context.
+
+## Props
+    children: ReactNode (required)
+    customBlocks: Record<string, ComponentType<BlockComponentProps>> — custom block-type renderers available to all descendants
+    onAction: (actionId: string, type: "confirm" | "cancel" | "undo") => void — default action handler for descendant blocks
+    agent: { name: string, icon?: IconInput } — default agent identity for assistant messages
+
+## Example
+```jsx
+<AICommandProvider
+  agent={{ name: 'Devadoot', icon: <IconSparkles /> }}
+  customBlocks={{ chart: ChartBlock }}
+  onAction={(id, type) => handleAction(id, type)}
+>
+  <AIConversation messages={messages} />
+</AICommandProvider>
+
+// Read the context in a descendant:
+function MyBlock() {
+  const ctx = useAICommand() // { customBlocks, onAction, agent } | null
+  // ...
+}
+```
+
+## Composability
+- **Configure once** — set `customBlocks`, `onAction`, and `agent` here; `AIConversation` and `BlockRenderer` read them via context. Per-component props still win over the context (prop overrides provider).
+- **`useAICommand()`** — returns the context (`{ customBlocks, onAction, agent }`) or `null` when no provider is mounted. Custom blocks can use it to reach the shared action handler.
+- **Optional** — `AIConversation`/`BlockRenderer` work without a provider if you pass their props directly; the provider is a convenience for app-wide config.
+
+## Gotchas
+- Client component — mount inside a client boundary.
+- `useAICommand()` returns `null` (not a throw) when there's no provider — guard for it in custom blocks.
+
+## Changes
+### v0.49.0
+- **Added** Component documentation (the AI layer is now covered by the docs gate + hosted MCP).

package/docs/components/ai/block-renderer.md

@@ -0,0 +1,59 @@
+# BlockRenderer
+
+- Import: @devalok/shilp-sutra/ai/block-renderer
+- Server-safe: No
+- Category: ai
+
+Renders an ordered list of typed AI "blocks" — the structured chunks an assistant/
+server emits instead of plain text. A registry maps each block's `type` to a React
+component; consumers can register their own types. This doc also covers the block
+system and how to author a custom block.
+
+## Props
+    blocks: Block[] (required) — ordered blocks to render
+    onAction: (actionId: string, type: "confirm" | "cancel" | "undo") => void — fired by interactive blocks (e.g. confirm)
+    customBlocks: Record<string, ComponentType<BlockComponentProps>> — extra type→component renderers, merged OVER the built-ins (prop wins over context)
+    staggerDelay: number — ms between each block's entrance animation (default 50)
+    className: string
+
+Block: { id?: string, type: string, data: Record<string, unknown>, confidence?: "high" | "medium" | "low" } (see ai/types)
+BlockComponentProps<T>: { data: T, blockId?: string, confidence?: "high" | "medium" | "low", onAction?: (actionId, type) => void }
+
+## Defaults
+    staggerDelay defaults to 50
+
+## Example
+```jsx
+// Render server-emitted blocks:
+<BlockRenderer
+  blocks={message.blocks}
+  onAction={(id, type) => handleAction(id, type)}
+/>
+
+// Register a custom block type:
+function ChartBlock({ data }) {
+  return <MyChart series={data.series} />
+}
+<BlockRenderer
+  blocks={message.blocks}
+  customBlocks={{ chart: ChartBlock }}
+/>
+```
+
+## Composability
+- **The block system** — the AI conversation renders assistant output as a `Block[]`. Each block has a `type` (string) and a `data` payload. `BlockRenderer` looks up the type in its registry and renders the matching component; an unknown type falls back to an `Alert` showing the raw JSON (so a new server-emitted type degrades gracefully instead of crashing).
+- **Built-in block types** (9): `text` (Markdown prose), `table` (tabular data), `confirm` (action confirmation — confirm/cancel buttons + a "Why this action?" rationale drawer), `success` / `error` / `info` (status messages), `loading` (pending indicator), `divider` (separator), `stat_row` (a row of metric cards, composes `StatCard`).
+- **Confidence** — every block may carry `confidence: "high" | "medium" | "low"`. Low-confidence blocks get a faint warning wash + a "Low confidence" chip (owned by the shared `BlockShell` wrapper, so the treatment is consistent across all block types). This is an AI-native affordance: the UI signals how sure the model is.
+- **Writing a custom block** — a block component receives `BlockComponentProps<T>` (`data`, `confidence`, `onAction`, `blockId`). Wrap your content in `BlockShell` to inherit the confidence treatment. Register it via `customBlocks` (on `BlockRenderer` or `AICommandProvider`) keyed by the `type` string your server emits.
+- **Two public block subpaths** — `text` and `error` import `react-markdown` + `remark-gfm` (a Markdown peer dependency). They were split out of the `ai/blocks` barrel in 0.40.0 so consumers don't pull those peers unless they render Markdown. Import them directly when needed: `@devalok/shilp-sutra/ai/blocks/text`, `@devalok/shilp-sutra/ai/blocks/error`.
+- **Provider merge** — `customBlocks` from `AICommandProvider` (context) are merged with the `customBlocks` prop; the prop wins on key collision. Same for `onAction`.
+
+## Gotchas
+- Client component — mount inside a client boundary.
+- Requires a mounted `MotionProvider` (block entrances respect reduced-motion).
+- Rendering `text`/`error` blocks requires the `react-markdown` + `remark-gfm` peer dependencies — install them if your blocks include Markdown.
+- The `ai/blocks/*` components are an implementation detail of the registry; consume blocks via `BlockRenderer`/`AIConversation`, not by importing each block (except the two documented Markdown subpaths).
+
+## Changes
+### v0.49.0
+- **Added** Component + block-system documentation (the AI layer is now covered by the docs gate + hosted MCP).

package/docs/components/ai/command-bar.md

@@ -0,0 +1,78 @@
+# CommandBar
+
+- Import: @devalok/shilp-sutra/ai/command-bar
+- Server-safe: No
+- Category: ai
+
+A unified AI command input with three layout variants. Supports natural-language
+submission (`onSubmit`) and, optionally, command-palette filtering (`groups`) in the
+same bar. Shows an animated brand-gradient border while processing.
+
+## Props
+    onSubmit: (query: string) => void — called on Enter (natural-language submission)
+    state: "idle" | "typing" | "processing" | "responded" — drives visual feedback (gradient border, placeholder)
+    groups: CommandGroup[] — when provided, enables command-palette filtering alongside AI submission
+    onSearch: (query: string) => void — fired as the query changes (palette mode)
+    emptyMessage: string — text when a palette search yields nothing
+    emptyState: ReactNode — replaces the default empty UI
+    variant: "hero" | "inline" | "floating" — layout (default "hero")
+    placeholder: string | string[] — static text, or an array that rotates on an interval
+    placeholderInterval: number — rotation interval in ms when placeholder is an array (default 4000)
+    greeting: string — text above the input (hero variant)
+    hints: string[] — hint strings below the input (hero variant)
+    agentName: string
+    agentIcon: ReactNode
+    open: boolean — controlled open state (floating variant)
+    defaultOpen: boolean — uncontrolled initial open (floating variant)
+    onOpenChange: (open: boolean) => void — floating variant
+    keybinding: string | string[] | false — global toggle for the floating bar (default "mod+j")
+    disabled: boolean
+    maxHeight: string | number — cap on the results/scroll region (default "320px")
+    children: ReactNode
+
+CommandGroup / CommandItem: shared with composed/command-palette (see that doc)
+
+## Defaults
+    variant defaults to "hero"
+    placeholderInterval defaults to 4000
+    keybinding defaults to "mod+j"
+    maxHeight defaults to "320px"
+
+## Example
+```jsx
+// Hero variant — the primary AI entry point on a dashboard:
+<CommandBar
+  variant="hero"
+  greeting="What can I help with?"
+  placeholder={['Summarize this project…', 'Draft a status update…', 'Find overdue tasks…']}
+  hints={['⌘J to open anywhere', 'Ask in plain English']}
+  state={aiState}
+  onSubmit={(q) => runAgent(q)}
+/>
+
+// Floating variant — global ⌘J overlay, palette + AI in one:
+<CommandBar
+  variant="floating"
+  keybinding="mod+j"
+  groups={commandGroups}
+  onSearch={setQuery}
+  onSubmit={(q) => runAgent(q)}
+/>
+```
+
+## Composability
+- **Two modes in one bar** — pass `onSubmit` for natural-language AI; add `groups` to also get command-palette filtering (arrow-key navigation, grouped items). Reuses `CommandGroup`/`CommandItem` from composed/command-palette.
+- **`floating` reuses the Dialog primitive** (`DialogContentRaw`) with a global keybinding — same overlay pattern as CommandPalette, so focus-trap/Escape/scroll-lock come for free.
+- **State-driven feedback** — set `state="processing"` to show the animated brand-gradient border; `"responded"` to settle it. Wire `state` to your agent's lifecycle.
+- **Placeholder rotation** — pass an array to `placeholder` for the rotating-prompt effect (paused while typing; respects reduced-motion).
+- **Pairs with `AIConversation`** — CommandBar is the input; AIConversation renders the response thread.
+
+## Gotchas
+- Client component — mount inside a client boundary.
+- Requires a mounted `MotionProvider`.
+- `keybinding` only applies to the `floating` variant; pass `false` to disable the global shortcut.
+- Largest component in the AI layer (3 variants share one implementation) — prefer `inline`/`hero` for embedded bars, `floating` for the app-wide launcher.
+
+## Changes
+### v0.49.0
+- **Added** Component documentation (the AI layer is now covered by the docs gate + hosted MCP).

package/docs/components/ai/conversation.md

@@ -0,0 +1,59 @@
+# AIConversation
+
+- Import: @devalok/shilp-sutra/ai/conversation
+- Server-safe: No
+- Category: ai
+
+A scrollable AI conversation thread: user + assistant turns, streaming processing
+steps, an agent header, and structured content blocks (rendered via BlockRenderer)
+with confirm/cancel/undo action support.
+
+## Props
+    messages: ConversationMessage[] (required) — ordered user + assistant turns
+    isProcessing: boolean — shows a live processing indicator below the last message
+    processingSteps: ProcessingStep[] — granular steps shown during processing (status: pending | active | done | error)
+    agent: { name: string, icon?: IconInput } — agent identity shown as a header on assistant messages
+    onAction: (actionId: string, type: "confirm" | "cancel" | "undo") => void — fired by action blocks
+    customBlocks: Record<string, ComponentType<BlockComponentProps>> — extra block-type renderers merged over the built-ins
+    maxHeight: string | number — max height of the container (enables scrolling)
+    autoScroll: boolean — auto-scroll to bottom on new messages (default true)
+    className: string
+
+ConversationMessage: { id: string, role: "user" | "assistant", blocks: Block[], ... } (see ai/types)
+ProcessingStep: { label: string, status: "pending" | "active" | "done" | "error" }
+
+## Defaults
+    autoScroll defaults to true
+
+## Example
+```jsx
+<AICommandProvider agent={{ name: 'Devadoot' }} onAction={handleAction}>
+  <AIConversation
+    messages={messages}
+    isProcessing={isThinking}
+    processingSteps={[
+      { label: 'Reading project', status: 'done' },
+      { label: 'Drafting reply', status: 'active' },
+    ]}
+    agent={{ name: 'Devadoot', icon: <IconSparkles /> }}
+    onAction={(id, type) => handleAction(id, type)}
+    maxHeight="60vh"
+  />
+</AICommandProvider>
+```
+
+## Composability
+- **Renders blocks, not raw text** — each assistant turn is a list of typed `Block`s rendered by `BlockRenderer`. See the block-renderer doc for the block system and how to register custom block types.
+- **Pairs with `AICommandProvider`** — the provider supplies `customBlocks`, `onAction`, and `agent` via context so you don't thread them through every message. Props on `AIConversation` win over context.
+- **Pairs with `CommandBar`** — CommandBar is the input surface (natural-language submission); AIConversation is the output thread. Common layout: CommandBar on top/bottom, AIConversation as the scroll region.
+- **Streaming** — set `isProcessing` + feed `processingSteps` to show step-by-step progress (Reading → Drafting → …) while the model works.
+- **Actions** — action blocks (e.g. `confirm`) call `onAction(actionId, type)`; wire it to your confirm/cancel/undo handlers.
+
+## Gotchas
+- Client component — mount inside a client boundary.
+- Requires a mounted `MotionProvider` (respects reduced-motion for the step spinner and block entrances).
+- `agent` set here labels assistant messages; `AICommandProvider`'s `agent` is the fallback when not passed per-conversation.
+
+## Changes
+### v0.49.0
+- **Added** Component documentation (the AI layer is now covered by the docs gate + hosted MCP).

package/docs/components/ai/devadoot-icon.md

@@ -0,0 +1,41 @@
+# DevadootIcon
+
+- Import: @devalok/shilp-sutra/ai
+- Server-safe: No
+- Category: ai
+
+The animated Devalok chakra glyph — the visual identity for the AI command system.
+Uses fill-first animation (the gradient color *is* the animation, Gemini-style),
+with a distinct state for idle, processing, responded, and error.
+
+## Props
+    state: "idle" | "processing" | "responded" | "error" — animation mode (default "idle")
+    size: number — pixel size (default 20)
+    className: string
+
+## Defaults
+    state defaults to "idle"
+    size defaults to 20
+
+## Example
+```jsx
+// Drive the icon from the agent lifecycle:
+<DevadootIcon state={isThinking ? 'processing' : hasReplied ? 'responded' : 'idle'} size={24} />
+
+// Error state:
+<DevadootIcon state="error" />
+```
+
+## Composability
+- **State-as-identity** — `idle` breathes pink↔rose slowly; `processing` sweeps a pink→purple→magenta gradient + glow; `responded` flashes bright then settles + a scale pop; `error` turns red with a glow pulse. Wire `state` to your agent's status.
+- **Pairs with `CommandBar` / `AIConversation`** — commonly placed in the CommandBar (hero/floating) or as the agent header avatar in the conversation.
+- **Exported from the `ai` barrel** — `import { DevadootIcon } from '@devalok/shilp-sutra/ai'` (no dedicated subpath).
+
+## Gotchas
+- Client component — mount inside a client boundary.
+- Requires a mounted `MotionProvider`; renders a static chakra when reduced-motion is set.
+- Brand-locked colors (Devalok pink↔purple palette) — it's a brand asset, not a generic spinner. Use `Spinner` for neutral loading.
+
+## Changes
+### v0.49.0
+- **Added** Component documentation (the AI layer is now covered by the docs gate + hosted MCP).

package/docs/components/composed/page-header.md

@@ -32,7 +32,7 @@
 - **Server-safe page-top header** with title + subtitle + breadcrumbs + actions slot. Renders Breadcrumb internally from the `breadcrumbs` array.
 - **Auto-derived title:** If `title` is omitted, the last breadcrumb's `label` becomes the h1. Saves duplication when the page title matches the breadcrumb leaf.
 - **Breadcrumb contract:** Last item should NOT have an `href` (it's the current page — renders as BreadcrumbPage, not a link). Items with `href` render as BreadcrumbLink.
-- **actions slot:** Typically one to three buttons (Save, Cancel, More). For larger action groups, use ButtonGroup or a toolbar.
+- **actions slot:** Typically one to three buttons (Save, Cancel, More). The slot wraps onto its own line under the title on narrow viewports instead of forcing horizontal overflow, so multiple/wide buttons are mobile-safe. For larger action groups, use ButtonGroup or a toolbar.
 - **Not for tabs / sub-navigation** — pair with Tabs rendered below PageHeader for that.
 
 ## Gotchas

package/docs/components/composed/responsive-modal.md

@@ -0,0 +1,66 @@
+# ResponsiveModal
+
+- Import: @devalok/shilp-sutra/composed/responsive-modal
+- Server-safe: No
+- Category: composed
+
+## Props
+
+### ResponsiveModal (root)
+    open: boolean (controlled open state)
+    defaultOpen: boolean (uncontrolled initial state)
+    onOpenChange: (open: boolean) => void
+    dismissable: boolean (default: true — when false, Escape / outside-click / drag cannot close; only an explicit Close or onOpenChange does)
+
+### ResponsiveModalContent
+    snapPoints: number[] (mobile only; ascending viewport-height fractions like [0.4, 0.9] the sheet rests at. Omit for a content-height sheet. Ignored on desktop)
+    defaultSnapPoint: number (mobile only; index into snapPoints the sheet opens at. Defaults to the last/tallest)
+
+## Defaults
+    dismissable=true
+
+## Example
+```jsx
+<ResponsiveModal>
+  <ResponsiveModalTrigger asChild><Button>Edit profile</Button></ResponsiveModalTrigger>
+  <ResponsiveModalContent snapPoints={[0.5, 0.9]}>
+    <ResponsiveModalBackground className="bg-linear-to-br from-accent-3 to-accent-6 opacity-40" />
+    <ResponsiveModalHeader>
+      <ResponsiveModalTitle>Edit profile</ResponsiveModalTitle>
+      <ResponsiveModalDescription>Changes save when you apply.</ResponsiveModalDescription>
+    </ResponsiveModalHeader>
+    <ResponsiveModalBody>{/* form fields — scrolls internally */}</ResponsiveModalBody>
+    <ResponsiveModalFooter>
+      <ResponsiveModalClose asChild><Button variant="soft">Cancel</Button></ResponsiveModalClose>
+      <Button>Apply</Button>
+    </ResponsiveModalFooter>
+  </ResponsiveModalContent>
+</ResponsiveModal>
+```
+
+## Composability
+- **Part:** ResponsiveModal (required) — root; owns open/close state and the desktop/mobile switch
+- **Part:** ResponsiveModalTrigger — opens the modal; use `asChild` to wrap your own button
+- **Part:** ResponsiveModalContent — the switching panel: centered Dialog at md+, bottom sheet below
+- **Part:** ResponsiveModalBackground (slot: behind) — optional full-bleed layer painted at `-z-10`, clipped to the panel radius
+- **Part:** ResponsiveModalHeader (slot: top) — pinned; stays put while the body scrolls
+- **Part:** ResponsiveModalTitle (required) — labels the dialog for accessibility
+- **Part:** ResponsiveModalDescription — optional subtitle
+- **Part:** ResponsiveModalBody — internal scroll region (min-h-0 flex-1 overflow-y-auto), capped 85dvh desktop / 90dvh mobile
+- **Part:** ResponsiveModalFooter (slot: bottom) — pinned action row; stacks on mobile, right-aligned inline on desktop
+- **Part:** ResponsiveModalClose — manual close (Content already renders a built-in close button when dismissable)
+- **Composes:** dialog (alternative-to) — use Dialog directly when you always want a centered modal
+- **Composes:** sheet (alternative-to) — use Sheet directly when you always want an edge panel
+- **Context:** ResponsiveModal — provides open / isMobile / dismissable / onClose to its parts via context
+
+## Gotchas
+- Built on the same dialog primitive as Dialog and Sheet — focus trap, Escape, scroll lock, and portal are handled. Not server-safe (uses hooks); import in a client component.
+- Put a `ResponsiveModalTitle` inside every modal — it sets the ARIA label. Omitting it triggers an accessibility warning.
+- The built-in close button sits at `z-10` above `ResponsiveModalBackground` (`-z-10`); keep Header/Body/Footer in normal flow (no `relative z-*` wrapper) or a positioned wrapper will paint over the close button and eat the tap.
+- `snapPoints` and `defaultSnapPoint` are mobile-only — they are ignored at md+ (always a centered Dialog).
+- Height caps live on the panel (85dvh desktop / 90dvh mobile); do not add your own `max-h` to `ResponsiveModalBody` — it already scrolls.
+- Prefer this over `DialogContent responsive` when the mobile form should be a partial bottom sheet; `responsive` collapses to a full-screen takeover that leaves dead space under short content.
+
+## Changes
+### v0.49.0
+- Added — new component. Dialog (md+) / bottom-sheet (mobile) responsive modal with pinned header/footer, internal scroll body, optional full-bleed background slot, drag-to-dismiss, and optional mobile snap points.

package/docs/components/composed/schedule-view.md

@@ -14,7 +14,7 @@
     endHour: number (default: 18, exclusive)
     slotDuration: number (minutes, default: 30)
 
-Event colors: "primary" | "success" | "warning" | "error" | "info" | "neutral"
+Event colors: "accent" | "success" | "warning" | "error" | "info" | "neutral"
 
 ## Defaults
     startHour=8, endHour=18, slotDuration=30
@@ -33,7 +33,7 @@ Event colors: "primary" | "success" | "warning" | "error" | "info" | "neutral"
 - **Day / Week calendar view** for time-block display (meetings, shifts, availability). Not a full calendar app — no month view, no drag-to-create.
 - **Event data is consumer-owned:** You pass `events` as an array; ScheduleView doesn't fetch, doesn't cache, doesn't expand recurring events. All scheduling logic lives in your app.
 - **Event click + slot click** — `onEventClick` for existing events; `onSlotClick` for creating new events (fires with start/end of the empty slot).
-- **Color vocabulary matches the DS** — `primary/success/warning/error/info/neutral`. Map your event types to these at the data layer.
+- **Color vocabulary matches the DS** — `accent/success/warning/error/info/neutral`. Map your event types to these at the data layer.
 - **endHour is exclusive:** `endHour=18` means the last visible slot starts at 17:30 (with 30min slots). Match your UX expectation: 9-5 typically means `startHour=9, endHour=18`.
 - **Pairs with date-picker/composed** — use DatePicker or DateRangePicker to choose which date to show; pass that as ScheduleView's `date`.
 
@@ -43,5 +43,9 @@ Event colors: "primary" | "success" | "warning" | "error" | "info" | "neutral"
 - Events that span outside `startHour`/`endHour` may be clipped
 
 ## Changes
+### v0.49.0
+- **BREAKING** `ScheduleEvent.color` value `"primary"` renamed `"accent"` (DS colour vocabulary). It was the default, so untyped events are unaffected.
+- **Added** keyboard focus rings on slot cells + event blocks; current-time indicator uses the shared `<Dot>`.
+
 ### v0.1.0
 - **Added** Initial release

package/docs/components/ui/breadcrumb.md

@@ -1,7 +1,7 @@
 # Breadcrumb
 
 - Import: @devalok/shilp-sutra/ui/breadcrumb
-- Server-safe: No
+- Server-safe: Yes
 - Category: ui
 
 ## Compound Components

package/docs/components/ui/checkbox.md

@@ -8,7 +8,7 @@
     checked: boolean | "indeterminate"
     onCheckedChange: (checked: boolean | "indeterminate") => void
     size: "sm" | "md" | "lg"
-    error: boolean (shows red border)
+    state: "default" | "error" | "warning" | "success" (validation border/bg tint; error sets aria-invalid. Inherited from FormField when omitted)
     indeterminate: boolean (overrides checked, shows dash icon)
     disabled: boolean
 
@@ -37,6 +37,9 @@
 - WCAG 2.5.8 minimum target size met at md (24px); sm (20px) may fail if not paired with enough label hit area
 
 ## Changes
+### v0.49.0
+- **BREAKING** Removed the `error: boolean` prop; use `state` (`FieldState = "default" | "error" | "warning" | "success"`). Migrate `<Checkbox error />` → `<Checkbox state="error" />`. Gains `warning`/`success` tints and now inherits state from `FormField`.
+
 ### v0.22.0
 - **Changed** Check indicator animation from scale-bounce to path-draw (stroke draws progressively). Indeterminate dash also draws in.
 - **Fixed** Uncontrolled checkbox never showed checkmark — `checked` from props was `undefined`, so `isActive` was always `false`. Now tracks internal state.

package/docs/components/ui/combobox.md

@@ -7,6 +7,7 @@
 ## Props
     options: ComboboxOption[] (REQUIRED) — { value: string, label: string, description?: string, icon?: ReactNode, disabled?: boolean }
     size: "xs" | "sm" | "md" | "lg" (trigger height)
+    state: "default" | "error" | "warning" | "success" (validation border tint; error sets aria-invalid. Inherited from FormField when omitted)
     DISCRIMINATED UNION — type depends on `multiple` flag:
     Single (default): multiple?: false, value?: string, onValueChange: (value: string) => void
     Multiple: multiple: true, value?: string[], onValueChange: (value: string[]) => void
@@ -50,6 +51,9 @@
 - Dropdown content is portalled to document.body — parent styles like `overflow: hidden` don't clip it, and container-scoped test queries won't find it
 
 ## Changes
+### v0.49.0
+- **Added** `state` prop (`FieldState = "default" | "error" | "warning" | "success"`) — unified field-state API. Renders a validation border tint + sets `aria-invalid`; inherits from `FormField` when omitted. (Additive — Combobox had no prior validation prop.)
+
 ### v0.18.0
 - **Added** `accessibleLabel` prop — custom aria-label for trigger, falls back to placeholder