@devalok/shilp-sutra 0.47.0 → 0.49.0

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/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/emoji-picker.md

@@ -11,9 +11,7 @@ EmojiPicker, EmojiPickerPopover
 
 ### EmojiPicker
     onSelect: (emoji: EmojiData) => void
-    theme: "auto" | "light" | "dark"
-    previewPosition: "top" | "bottom" | "none"
-    skinTonePosition: "search" | "preview" | "none"
+    emojibaseUrl: string (base URL for the emoji dataset; default = frimousse's jsdelivr CDN)
     className: string
 
 ### EmojiPickerPopover (extends EmojiPicker props)
@@ -26,7 +24,7 @@ EmojiPicker, EmojiPickerPopover
     shortcodes: string
 
 ## Defaults
-    theme="auto", previewPosition="none", skinTonePosition="search", align="start"
+    align="start"
 
 ## Example
 ```jsx
@@ -34,27 +32,31 @@ EmojiPicker, EmojiPickerPopover
   <Button variant="ghost" size="icon-sm">😀</Button>
 </EmojiPickerPopover>
 
-<EmojiPicker onSelect={handleEmoji} theme="dark" />
+<EmojiPicker onSelect={handleEmoji} />
 ```
 
 ## Composability
 - **Two exports:** `EmojiPicker` (inline grid, no trigger) and `EmojiPickerPopover` (trigger + popover wrapper). Use EmojiPickerPopover 95% of the time — trigger-on-click is the standard UX.
-- **Wraps @emoji-mart/react**, lazy-loaded with a Skeleton placeholder while the ~200KB bundle fetches. Don't pre-import unless you need it eagerly.
+- **Built on frimousse**, bundled and lazy-loaded (own `emoji` chunk, incl. the dataset). Needs no consumer peer install and no React-19 peer workaround. Don't pre-import unless you need it eagerly.
+- **Native emoji only.** Each platform renders its own glyphs. Theme follows the surrounding `.dark` class via DS tokens automatically — no theme prop.
+- **Built-in footer:** a live preview of the hovered/active emoji (frimousse `ActiveEmoji`) plus a skin-tone selector (`SkinToneSelector`) — no props needed.
+- **Dataset source / CSP:** frimousse fetches the emoji dataset from jsdelivr at runtime. To remove the CDN dependency (strict CSP, offline, air-gapped), copy `node_modules/emojibase-data` into your app's `public/emojibase` and pass `emojibaseUrl="/emojibase"`.
 - **Trigger composition:** EmojiPickerPopover's `children` is the trigger — wrap any Button/IconButton. Typical pairing is an icon-only IconButton with a 😀 label.
-- **TipTap integration:** Use `createEmojiSuggestion(set?)` factory to create a TipTap suggestion plugin that opens the picker on typing `:emoji`. Works with RichChatInput and RichTextEditor.
-- **Theme matching:** `theme="auto"` reads the `.dark` class on `<html>` — matches the DS dark mode toggle automatically. Override with explicit light/dark.
-- **Emoji sets:** Pass `set="apple" | "google" | ...` for consistent cross-platform emoji art (defaults to native OS glyphs).
+- **TipTap integration:** Use `createEmojiSuggestion()` (from `./extensions/emoji-suggestion`) to open a `:shortcode:` suggestion list. Works with RichChatInput and RichTextEditor.
 
 ## Gotchas
-- Wraps `@emoji-mart/react` which is lazy-loaded — shows a Skeleton placeholder while loading
-- `theme="auto"` reads the `.dark` class on `<html>` to pick light/dark
-- EmojiPickerPopover auto-closes after selection
+- Client-only (fetches its emoji dataset on first open) — not server-safe.
+- EmojiPickerPopover auto-closes after selection.
+- The `set` / `theme` / `previewPosition` / `skinTonePosition` props are deprecated no-ops kept for source compatibility; the picker is native-only.
 
 ## Changes
 
+### v-next
+- **Breaking** picker migrated from `@emoji-mart/react` to `frimousse` — native emoji only. Art-style sets (apple/google/twitter/facebook) removed; `set`/`theme`/`previewPosition`/`skinTonePosition` are now no-ops.
+- **Breaking** `emojiDataLoaders` export removed; `EmojiNodeAttrs` narrowed to `{ id, native }`; `createEmojiSuggestion()` takes no argument; `EmojiSuggestionItem` no longer has `x`/`y`.
+- **Changed** frimousse + `@emoji-mart/data` are now bundled (lazy `emoji` chunk) — the emoji feature needs zero consumer peer installs.
+- **Added** built-in footer: active-emoji preview + skin-tone selector. New `emojibaseUrl` prop to self-host the dataset (remove the runtime CDN dependency).
+
 ### v0.33.0
-- **Added** `set` prop on EmojiPicker and EmojiPickerPopover — `EmojiSet` type: 'native' | 'apple' | 'google' | 'twitter' | 'facebook'
-- **Added** `EmojiNode` TipTap extension — inline atom node with spritesheet rendering for consistent emoji art styles
-- **Added** `createEmojiSuggestion(set?)` factory — replaces `EmojiSuggestion` named export
-- **Added** `EmojiSet` type exported from barrel
-- **Breaking** `EmojiSuggestion` named export removed — use `createEmojiSuggestion()` factory
+- **Added** `EmojiNode` TipTap extension and `createEmojiSuggestion()` factory.
+- **Breaking** `EmojiSuggestion` named export removed — use `createEmojiSuggestion()` factory.

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/rich-text-editor.md

@@ -58,7 +58,7 @@ MentionItem: { id: string; label: string; avatar?: string }
 
 ## Gotchas
 - Tiptap is bundled — no need to install `@tiptap/*` packages separately
-- Emoji picker requires `@emoji-mart/react` + `@emoji-mart/data` peers
+- Emoji picker (frimousse) + its dataset are bundled too — no emoji peers to install (native-only since the frimousse migration)
 - Images without `onImageUpload` are stored as base64 in HTML — large images bloat content
 - Mention rendering in viewer always works (no mention props needed, just the HTML)
 - Features: bold, italic, underline, strikethrough, highlight, headings, blockquote, lists, task lists, code, links, images, file attachments, mentions, emoji, text alignment, horizontal rule

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
 

package/docs/components/ui/dot.md

@@ -0,0 +1,61 @@
+# Dot
+
+- Import: @devalok/shilp-sutra/ui/dot
+- Server-safe: No
+- Category: ui
+
+A small semantic status/indicator dot — the low-level primitive behind status
+pills, presence indicators, legend swatches, and `StatusDot`. Intent-coloured,
+sized, optionally pulsing, filled or ring.
+
+## Props
+    color: "accent" | "success" | "warning" | "error" | "info" | "neutral" | "current" (intent colour; `current` inherits text colour)
+    size: "xs" | "sm" | "md" | "lg"
+    variant: "filled" | "ring" | "off" (`off` = faint fill + light border, i.e. inactive)
+    withBorder: boolean (contrast ring so the dot stays visible on busy/coloured backgrounds)
+    pulse: boolean (animate a pulsing ripple; ignored for `off`)
+    pulseSpeed: "slow" | "normal" | "fast" (pulse tempo)
+    label: ReactNode (inline text; makes the dot an announced status)
+    labelPosition: "start" | "end" (which side the label sits on)
+    labelClassName: string
+
+## Defaults
+    color: "neutral"
+    size: "md"
+    variant: "filled"
+    withBorder: false
+    pulse: false
+    pulseSpeed: "normal"
+    labelPosition: "end"
+
+## Example
+```jsx
+<Dot color="success" />                                 {/* bare, decorative */}
+<Dot color="error" pulse pulseSpeed="fast" label="Recording" />  {/* pulsing + announced */}
+<Dot color="neutral" variant="off" label="Offline" />  {/* inactive: faint fill + light border */}
+<Dot color="success" withBorder />                      {/* contrast ring for busy backgrounds */}
+<Dot color="accent" label="3 online" labelPosition="start" />  {/* label before the dot */}
+<Dot color="neutral" variant="ring" size="lg" />        {/* hollow ring */}
+
+// As leading content in a pill:
+<Badge variant="soft" color="warning" startIcon={<Dot color="warning" size="sm" />}>
+  Pending
+</Badge>
+```
+
+## Composability
+- **Decorative vs announced.** A bare `<Dot>` is `aria-hidden` (the surrounding element carries meaning — e.g. a Badge's text). Pass a `label` (or `aria-label`) to make it a `role="status"` announced indicator.
+- **Intent colour, shared vocabulary.** `color` uses the same intent names as the rest of the system (`accent/success/warning/error/info/neutral`), so a Dot next to a Badge/Button of the same intent matches.
+- **`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.
+- **`pulseSpeed`** (slow/normal/fast) tunes the pulse tempo — fast for urgent (recording), slow for ambient (syncing).
+
+## Gotchas
+- A bare dot is decorative by design — if a dot is the *only* signal (no adjacent text), give it a `label` or `aria-label` so it's announced.
+- `pulse` respects `prefers-reduced-motion` (the ripple is disabled).
+
+## Changes
+### v0.49.0
+- **Added** Initial release. Extracted as the shared primitive behind `StatusDot`, `StatusBadge`, and `Badge`'s dot. Colours `accent/success/warning/error/info/neutral/current`; sizes `xs–lg`; variants `filled/ring/off`; `withBorder` contrast ring; `pulse` + `pulseSpeed`; `label` + `labelPosition`.