@nurix/etna 0.20.37 → 0.20.38

package/data/harnesses/code/skills/design/components/layout.md

@@ -2,51 +2,111 @@
 
 > Generated reference (regen-owned; see [index.md](index.md)). Binds only under `primitives: nurix`.
 
-Content structure and containers. Import each from its own subpath, e.g. `import { Card, CardContent } from "@nurix/components/block/card";`.
+Components: Accordion, AspectRatio, Block, Card, Carousel, Collapsible, Item, Resizable, Row, ScrollArea, Separator, SidePanel, Sortable, Spacer
 
-## Statistics
+Each imports from its own subpath as one namespace, with its parts as dotted members, e.g. `import { Card } from "@nurix/components/block/card"` then `Card.Header`, `Card.Content`, `Card.Footer`. Parts swap their element through `render` — there is no `asChild` (Resizable's parts are the exception: they take no `render`).
 
-Compound schema for dashboard stat / KPI cards — compose only the regions a card needs. Import from `@nurix/components/statistics`. Sub-components throw if rendered outside `<Statistics>`. The wrapper is `bare` (invisible — just a flex column) by default so consumers own its look; opt into a surface with `variant`.
+## Block · Row · Spacer
 
-**Sub-components:** `StatisticsHeader`, `StatisticsIcon`, `StatisticsHeading`, `StatisticsTitle`, `StatisticsDescription`, `StatisticsActions`, `StatisticsSection`, `StatisticsMetric`, `StatisticsValue`, `StatisticsUnit`, `StatisticsTrend`, `StatisticsComparison`, `StatisticsGroup`, `StatisticsVisual`, `StatisticsGauge`, `StatisticsProgress`, `StatisticsSegmentedBar`, `StatisticsSparkline`, `StatisticsLegend`, `StatisticsLegendItem`, `StatisticsContent`, `StatisticsFooter`, `StatisticsCaption`, `StatisticsLink`
+The naked space primitives: `Block` (`block/block`) is a page region that stacks its children on the density gap and owns the region's insets; `Row` (`element/row`) owns only the gap between its children; `Spacer` (`element/spacer`) is placed empty space that pushes siblings apart. None of them draws anything — the dress is `className`.
 
-**Statistics props:** `size` [sm|md|lg] (headline value scale), `variant` [bare|card|elevated|outline|soft|ghost] (default `bare` draws nothing; the rest add padding + surface), `accent` [none|primary|success|warning|danger|info], `gap` [none|sm|md|lg], `justify` [start|center|end|between|around|evenly], `comparisonLabel`
-**StatisticsTitle:** `size` [sm|md|lg], `align` [left|center|right]
-**StatisticsTrend:** `value:number`, `direction?` [up|down], `invert?` (flip color, keep arrow), `pill?`, `format?:(n)=>string`
-**StatisticsIcon:** `variant` [default|primary|success|warning|danger|info], `tone` [soft|solid|outline|plain], `size` [xs|sm|md|lg|xl|oversized] (oversized bleeds out the top-right corner — needs a clipping surface variant), `shape` [circle|rounded|square]
-**StatisticsGauge:** `value` (0–100), `sweep?` [180|270], `size?`, `thickness?`, `trackColor?`, `fillColor?` — renders children centered in the dial
-**StatisticsSection:** `gap`, `justify` — a vertical group; nest two (top + bottom) in a `justify="between"` card to pin clusters to the top and bottom. `StatisticsVisual` is a generic slot: drop in a built-in visual or any chart (`PieGraph`, `LineGraph`, `BarGraph`, `ProgressBar`).
+**Block props:** `render` (root element, default `section` — `<header />`, `<footer />`, `<aside />`, `<main />`), `height` [hug|hero] (default `hug`; `hero` reserves a 300px masthead band), `shouldSettle` (a content-driven height change travels instead of snapping; outermost settling region only)
+**Row props:** `gap` [none|sm|md|lg] (default `md`, on the `--density-gap-*` tokens), `align` [start|center|end|baseline] (default `center`), `hasFloor` (reserves one control height, so a toolbar row measures the same with or without its buttons), `render`
+**Spacer props:** `render` only — no size, no content; `aria-hidden`, and it grows only inside a flex parent
+
+- Insets live only on the Block: never pad a Row or Spacer inside it, never put margins on its children.
+- Distribution is positional — a Spacer between the sides replaces `justify-between` and `mt-auto`. Never use it for a fixed distance; that is the parent's gap.
 
 ```tsx
-<Statistics variant="card" comparisonLabel="vs last week">
-  <StatisticsHeader>
-    <StatisticsHeading>
-      <StatisticsTitle>Revenue</StatisticsTitle>
-    </StatisticsHeading>
-    <StatisticsActions>
-      <StatisticsIcon variant="success">{/* icon */}</StatisticsIcon>
-    </StatisticsActions>
-  </StatisticsHeader>
-  <StatisticsMetric>
-    <StatisticsValue>$21,434</StatisticsValue>
-    <StatisticsTrend value={-12.2} invert pill />
-    <StatisticsComparison />
-  </StatisticsMetric>
-</Statistics>
+<Block render={<header />} className="border-b bg-card">
+  <Row hasFloor>
+    <Breadcrumb />
+    <Spacer />
+    <Button>New</Button>
+  </Row>
+</Block>
+```
+
+## Card
+
+The surfaced container (`block/card`): ring edge, elevation and density insets, with a header grid that grows an end column only when an action is present.
+
+**Sub-components:** `Card.Header` (`hasDivider`), `Card.Header.Action` (pinned to the header's end column), `Card.Title`, `Card.Description`, `Card.Content`, `Card.Footer` (`hasDivider`)
+
+- No `padding`/`radius`/`shadow` props: insets read the `--density-pad-*` tokens. Depth rides `className` as `shadow-(--elevation-N)` or `shadow-none`, which keeps the ring edge.
+- `hasDivider` draws the hairline rule and the density inset on that side; a bare `border-b` / `border-t` class adds no inset.
+- A Title mints an id; the root points `aria-labelledby` at it only while the root carries a role (`role`, or `render={<section />}` / `article` / `aside` / `form` / `nav` / `fieldset`).
+- Full-bleed media is a direct `<img>` child of `Card`. A grid of clickable cards is `block/list` with `view="card"`; there is no action-area part.
+
+```tsx
+<Card render={<section />}>
+  <Card.Header hasDivider>
+    <Card.Title render={<h2 />}>Billing</Card.Title>
+    <Card.Description>Plan and payment method</Card.Description>
+    <Card.Header.Action><Button variant="ghost" size="sm">Edit</Button></Card.Header.Action>
+  </Card.Header>
+  <Card.Content>{/* … */}</Card.Content>
+  <Card.Footer hasDivider><Button>Upgrade</Button></Card.Footer>
+</Card>
+```
+
+## Item
+
+A list or menu row primitive (`element/item`): leading media, a title and description, trailing actions.
+
+**Sub-components:** `Item.Media` (`variant` [default|icon|image]), `Item.Content`, `Item.Title`, `Item.Description`, `Item.Actions` (a `role="group"` labelled by the row's Title), `Item.Header`, `Item.Footer`, `Item.Group`, `Item.Separator`
+**Item props:** `variant` [default|outline|muted], `inset` [default|sm], `side` [start|end] (`end` reverses the row), `render` (`render={<a href="…" />}` makes the whole row a link; an untyped `<button />` becomes `type="button"`)
+
+- `Item.Media variant="image"` is what crops and sizes an `<img>`; `icon` is a bordered tile.
+- `Item.Group` inserts no dividers and carries no list role — place `Item.Separator` yourself, and write `<Item.Group render={<ul />}>` with rows `render={<li />}` for list semantics.
+- Data-driven rows with search, grouping or pagination are `block/list` with `Item` rows.
+
+```tsx
+<Item variant="outline">
+  <Item.Media variant="icon"><Bell /></Item.Media>
+  <Item.Content>
+    <Item.Title>Deploy finished</Item.Title>
+    <Item.Description>web-app shipped to production.</Item.Description>
+  </Item.Content>
+  <Item.Actions><Button variant="ghost" size="sm">View</Button></Item.Actions>
+</Item>
+```
+
+## Sortable
+
+Drag-to-reorder list over dnd-kit (`compound/sortable`), keyboard sortable, with a floating drag overlay. Optional peer family `sortable` — install `@dnd-kit/core`, `@dnd-kit/modifiers`, `@dnd-kit/sortable` and `@dnd-kit/utilities` yourself.
+
+**Sub-components:** `Sortable.Content`, `Sortable.Item` (`value`, `isHandle` drags the whole row), `Sortable.ItemHandle` (the grip), `Sortable.Overlay` (the drag preview, portalled to `document.body` or a `container`)
+**Props:** `value` / `defaultValue` / `onValueChange(value, details)` (an uncontrolled caller refuses a move with `details.cancel()`), `onValueCommitted`, `getItemValue` (stable unique id; required when `value` holds objects), `orientation` [vertical|horizontal|mixed] (default `vertical`), `strategy`, `activationConstraint` (`distance` px or `delay` ms), `hasGrabCursor` (default on), `disabled`, `labels`
+
+- Also exported: `useSortableItem`, `arrayMove`, `arraySwap`, the list/rect strategies, the `restrictTo*` and snap modifiers, and the collision detectors.
+- Skip `Sortable.Overlay` and a dragged item only shifts in place, with nothing following the pointer.
+
+```tsx
+<Sortable value={items} onValueChange={setItems} getItemValue={(item) => item.id}>
+  <Sortable.Content>
+    {items.map((item) => (
+      <Sortable.Item key={item.id} value={item.id}><Sortable.ItemHandle />{item.name}</Sortable.Item>
+    ))}
+  </Sortable.Content>
+  <Sortable.Overlay />
+</Sortable>
 ```
 
 ## Other layout components
 
-- `accordion` — Accordion, AccordionItem, AccordionTrigger, AccordionContent
-- `aspect-ratio` — AspectRatio
-- `bento-grid` — BentoGrid, BentoCard
-- `card` — Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter, CardAction, CardImage
-- `carousel` — Carousel, CarouselContent, CarouselItem, CarouselPrevious, CarouselNext
-- `collapsible` — Collapsible, CollapsibleTrigger, CollapsibleContent
-- `collapsible-panel` — CollapsiblePanel
-- `editable-card` — EditableCard, EditableCardHeader, EditableCardBody, EditableCardFooter
-- `resizable` — ResizablePanelGroup, ResizablePanel, ResizableHandle
-- `scroll-area` — ScrollArea, ScrollBar
-- `separator` — Separator
-- `separator-with-text` — SeparatorWithText
-- `sortable` — Sortable, SortableContent, SortableItem, SortableItemHandle, SortableOverlay
+- `compound/accordion` — `Accordion` with `Accordion.Item`, `.Header` (an `<h3>` by default; `render={<h4 />}` moves the level), `.Trigger`, `.Panel` (`hiddenUntilFound`, `keepMounted`); `value`/`defaultValue` are always arrays, `multiple` lets several stay open, `onValueChange` drives it from outside.
+- `element/collapsible` — `Collapsible` with `Collapsible.Trigger` (`render` swaps the button), `.Panel` (unmounts when closed unless `keepMounted`; never give it a height class), `.Indicator` (turns on the trigger's `data-panel-open`); `open`/`defaultOpen`/`onOpenChange`.
+- `block/side-panel` — `SidePanel` with `SidePanel.Trigger`, `SidePanel.Panel`: an in-flow region in a `flex` row that collapses to a rail and reflows its sibling; `side` [start|end] (default `end`), `open`/`onOpenChange`, `expandedWidth`/`collapsedWidth` (or the `--side-panel-expanded-width`/`--side-panel-collapsed-width` variables), `keepMounted`, `labels`.
+- `block/resizable` — `Resizable` with `Resizable.Panel`, `Resizable.Handle` (`hasGrip`): draggable split panes inside a parent with a height; a numeric size is pixels and a string is a percentage (`defaultSize="30%"`), `orientation` [horizontal|vertical], `onLayoutCommitted` + `defaultLayout` persist the layout, `panelRef`/`groupRef` reach the imperative handles. Optional peer family `resizable` (`react-resizable-panels`).
+- `compound/carousel` — `Carousel` with `Carousel.Content`, `.Item` (`basis-full` by default), `.Previous`, `.Next`; `value`/`defaultValue`/`onValueChange` (0-based snap index), `orientation`, `opts`, `setApi`, `labels`. `LoadingCarousel` is the ready-made tips strip (`data` tips with a stable `id`, `timeout`, `indicators` [progress|steps|none], `aspectRatio`, `textPlacement`). Optional peer family `carousel` (`embla-carousel-react`, `embla-carousel-autoplay`).
+- `element/scroll-area` — `ScrollArea`: styled bars on both axes, each drawn only while its axis overflows; give it an explicit `h-*`/`max-h-*`, `hasFadeEdges` fades every edge with more content past it, and `aria-label` names the focusable viewport. Never pass `ScrollArea.Bar` as a child.
+- `element/separator` — `Separator`: a hairline, `orientation` [horizontal|vertical] (vertical needs a bounded height); children render the labeled form, placed by `align` [start|center|end] (default `center`, ignored without children).
+- `element/aspect-ratio` — `AspectRatio`: `ratio` is width / height (default `1`; a non-finite or non-positive ratio falls back to `1`), the child fills the box itself (`h-full w-full object-cover`), `render` swaps the element.
+
+## Fallback-only concepts
+
+No primitive ships for these; build them from the catalog's fallback spec, composed over the components above.
+
+- `bento-grid` — an asymmetric CSS grid of `Card`s with spanning cells.
+- `editable-card` — a `Card` whose `Card.Content` edits in place and whose `Card.Footer` commits.

package/data/harnesses/code/skills/design/components/media.md

@@ -2,65 +2,86 @@
 
 > Generated reference (regen-owned; see [index.md](index.md)). Binds only under `primitives: nurix`.
 
-Icons, avatars, and media display; import each from its kebab-case subpath, e.g. `import { Avatar } from "@nurix/components/element/avatar"`.
+Avatars, icons, images, the brand mark and a few media-adjacent controls; import each from its layer-prefixed subpath, e.g. `import { Avatar } from "@nurix/components/element/avatar"`.
 
 ## Avatar
 
-Wraps `facehash` (deterministic identicon fallback) with default sizing.
+Profile image with an initials fallback and one stable accessible name, over Base UI's avatar. `AvatarGroup` stacks avatars into a facepile.
 
-**Props:** `size` (number, default 32) — sets both `width`/`height` and drives the round mask
+**Props:** `label` (the one accessible name, `role="img"`; omit beside a visible name and the avatar is `aria-hidden`), `size` [xs|sm|default|lg] (24, 32, 36, 40px; default `default`)
 
-**Sub-components:** `AvatarImage`, `AvatarFallback` (`colors` — palette forwarded to facehash for its generated background, defaults to a 10-color set)
+**Sub-components:** `Avatar.Image`, `Avatar.Fallback` (shows while the image loads and after it errors), `Avatar.Badge` (`intent` [neutral|info|success|warning|danger], status dot painted from `--intent-*`), `AvatarGroup` (`variant` [default|bare] — `bare` drops the hover lift; `role="group"`, name it with `aria-label`), `AvatarGroup.Count`
 
 ```tsx
-<Avatar size={40}>
-  <AvatarImage src="/photo.jpg" />
-  <AvatarFallback name="jane@example.com" />
+<Avatar label="Jane Doe, online" size="lg">
+  <Avatar.Image src={user.avatarUrl} alt="" />
+  <Avatar.Fallback>JD</Avatar.Fallback>
+  <Avatar.Badge intent="success" />
 </Avatar>
 ```
 
 ## CopyButton
 
-Click-to-copy button with a check/copy icon swap.
+Click-to-copy `Button` (`compound/copy-button`) that swaps its copy glyph for a check, publishes the outcome as `data-status` [success|error] and announces it.
 
-**Props:** `value`, `onCopy`, `copiedDuration` (ms before reverting, default 2000), `variant` [default|outline], `size` [sm|default|lg]
+**Props:** `value` (string, or a function resolved at click time), `onCopy(value)`, `onCopyError(error)`, `timeout` (ms the outcome holds; defaults to the `--hold-dwell` token, `Infinity` holds success), `labels` (`{ copy, copied, failed }`), plus Button's `variant` (default `ghost`), `intent`, `size` [xs|sm|default|lg] and `isIconOnly` (on when there are no `children`)
 
 ```tsx
-<CopyButton value={apiKey} size="sm" />
+<CopyButton value={message.text} size="sm" />
 ```
 
-## Logo
+## FilePreview
+
+One file tile — a staged attachment or a persisted file (`compound/file-preview`). It renders state only; choosing and uploading the file is `compound/file-picker`.
 
-Official brand logo — NuPlay mark + wordmark, inline SVG.
+**Sub-components:** `FilePreview.Group` (snap-scrolling strip), `FilePreview.Media`, `FilePreview.Content`, `FilePreview.Title`, `FilePreview.Description`, `FilePreview.Actions`, `FilePreview.Action`, `FilePreview.Trigger` (overlay button or `render` anchor), `FilePreview.Progress`; also `getFileTypeIcon({ type, name })`
 
-**Props:** `variant` [blue-black|white-white|lime-white|blue-white] (fixed brand colorways, named mark-then-wordmark; blue-black is the default for light surfaces, the white-wordmark variants are for dark/animated backdrops), `height` (number|string, sizes via intrinsic aspect ratio)
+**Props:** root — `status` [idle|uploading|processing|error|success] (omit for a resting file; `idle` dashes the border, `error` tints it), `size` [default|sm|xs], `orientation` [horizontal|vertical], `variant` [default|bare]; Media — `type`, `name` (picks a mime-aware glyph when given no child), `variant="image"`; Progress — `value` (0–100, `null` indeterminate), `variant` [linear|circular|fill], `keepMounted` (otherwise it unmounts at 100)
 
 ```tsx
-<Logo variant="white-white" height={20} />
+<FilePreview status={file.status} size="sm">
+  <FilePreview.Media type={file.type} name={file.name} />
+  <FilePreview.Content>
+    <FilePreview.Title>{file.name}</FilePreview.Title>
+    <FilePreview.Description>{formatBytes(file.size)}</FilePreview.Description>
+  </FilePreview.Content>
+  <FilePreview.Actions>
+    <FilePreview.Action aria-label={`Remove ${file.name}`} onClick={() => remove(file.id)}><XIcon /></FilePreview.Action>
+  </FilePreview.Actions>
+</FilePreview>
 ```
 
-## ThemeToggler
+## Icon
 
-Light/dark toggle with a directional wipe reveal; cycles light → dark → system → light and persists to `localStorage`.
+Draws a Lucide icon from a name held as data (`element/icon`) — a record field, a config value or an `IconPicker` (`compound/icon-picker`) pick. A fixed icon known at build time is a direct `lucide-react` import instead.
 
-**Props:** `style` [icon|text-icon|icon-text], `size` [sm|md|lg], `duration` (ms, default 700)
+**Props:** `value` (Lucide's kebab-case name, e.g. `"arrow-up-right"`), `size` (numeric px, default 24), `label` (standalone meaningful icon → `role="img"`; omit beside visible text), `fallback` (drawn for an unknown name; an empty box of the icon's size otherwise), `strokeWidth` (defaults to the `--edge-stroke` token)
 
 ```tsx
-<ThemeToggler style="icon-text" size="md" />
+<Icon value={record.icon} size={16} />
 ```
 
-## ViewSwitcher
+## Image
 
-Segmented control for switching a view-type projection (e.g. table/card), with an animated sliding background.
+Content photo or screenshot (`element/image`) with a skeleton while loading and a bordered placeholder (the `alt` text, or `labels.unavailable` — "Image unavailable") on error or an empty `src`, never the native broken-image glyph. A person's photo is `Avatar`.
 
-**Props:** `value`/`onChange` (controlled), `defaultValue` (default `"table"`), `options` (`{ value, label, icon }[]`, defaults to Table/Card), `size` [sm|md|lg]
+**Props:** `src`, `alt`, `width`/`height` (both together reserve the box via `aspect-ratio`), `fallback` (replaces the placeholder glyph and caption), `labels` (`{ unavailable }`), `variant` [default|bare] (`bare` drops its own radius, border and fill inside a framing host). Takes no `onClick` — a lightbox wraps it in a trigger.
 
 ```tsx
-<ViewSwitcher value={view} onChange={setView} size="sm" />
+<Image src={attachment.src} alt={attachment.name} width={320} height={180} />
+```
+
+## Logo
+
+Official NuPlay brand lockup (`element/logo`) — mark + wordmark, inline SVG.
+
+**Props:** `variant` [blue-black|white-white|lime-white|blue-white] (fixed literal fills, named mark-then-wordmark; default `blue-black`, for light surfaces only), `height` (number = px; default 28px via `h-7`; width follows the aspect), `label` (accessible name, default `"NuPlay"`; pass `aria-hidden` beside the brand name in text). `fill` is not a prop — recolor through `variant`.
+
+```tsx
+<Logo variant="white-white" height={20} />
 ```
 
 ## Other Components
 
-- `icon-renderer` + `icons-data` — `IconRenderer`: `icon`/`family`/`size` [sm|md|lg|xl]/`color`; resolves a remote SVG from the configured icon CDN (`<cdn>/fa/<family>/<icon>.svg`) tinted via CSS filter, with a built-in fallback icon on load error. `icons-data` exports `iconsData` — `{ name, categories, tags }[]` — for building icon pickers over the local Lucide set (distinct from the remote family above).
-- `live-waveform` + `mic-icon` — `LiveWaveform`: canvas mic-level visualizer; `active`, `processing`, `mode` [static|history|frequency], `barWidth`/`barGap`/`barRadius`/`barColor`, `sensitivity`, `onStreamReady`/`onStreamEnd`/`onError` (draft API — most props are untyped passthroughs). `MicIcon`: animated mic glyph with an imperative ref (`startAnimation`/`stopAnimation`); `size`, `duration`, `isAnimated`.
-- `shine-border` — `ShineBorder`: absolutely-positioned animated gradient border overlay (parent needs `position: relative`); `borderWidth`, `duration` (seconds), `shineColor` (string or array, cycled through a radial gradient sweep)
+- `lib/icons-data` — `iconsData`: `{ name, categories, tags }[]` over the Lucide set (~1,700 entries), for a custom icon search or browser; load it with a dynamic `import()`, keep only names present in the installed `lucide-react`, and render each match with `Icon`. A one-icon pick is `IconPicker` (`compound/icon-picker`), which takes these records as `data`.
+- View switching (table/card and similar view-mode strips) has no dedicated component: compose a single-select `ToggleGroup` + `ToggleGroup.Item` (`compound/toggle-group`), guarding the `""` it publishes on deselect; reach for `Tabs` (`compound/tabs`) only when the pick also swaps a visible panel.

package/data/harnesses/code/skills/design/components/motion.md

@@ -2,81 +2,91 @@
 
 > Generated reference (regen-owned; see [index.md](index.md)). Binds only under `primitives: nurix`.
 
-Animation primitives built on the `motion` library (`motion-primitives/*`) plus a small `animate-ui/*` layer. Compose sparingly — decorative and low-frequency surfaces only; never on data or on actions users repeat dozens of times a day. Import each from its own subpath, e.g. `import { AnimatedGroup } from "@nurix/components/effect/animated-group"`.
+The effect tier (`effect/*`; the streaming cursor is a conversation surface, in [collections.md](collections.md)) plus the `element/animated-number` counter and the motion-aware `lib/slot`. Compose sparingly — decorative and low-frequency surfaces only; never on data or on actions users repeat dozens of times a day. Import each from its own subpath, e.g. `import { AnimatedList } from "@nurix/components/effect/animated-list"`.
 
-## Animated numbers
+Every effect times itself from the personality's motion ladder: durations follow the `pace` trait, and the caller periods below (seconds at neutral pace unless marked) scale with it. No effect takes a `transition`, `variants` or `initial` prop. Under `prefers-reduced-motion`, a zeroed ladder, or inside a `data-mode="inline"` collection, an effect goes still: a continuous effect renders its static frame and publishes `data-playing="false"` (it also pauses off screen and in a hidden tab), and a one-shot effect lands in its end state and publishes `data-reduced-motion`. Where an effect takes `as`, the value is a tag from the tier's closed motion tag table.
 
-Tick-up numerals that render as plain text until JS is ready (no layout shift, no flash of `0`).
+## Animated numbers
 
-- `motion-primitives/animated-number` — `AnimatedNumber`: spring-interpolated count-up; `value`, `springOptions`, `as` (element/component, default `span`)
-- `motion-primitives/sliding-number` — `SlidingNumber`: per-digit slot-machine roll; `value`, `padStart`, `decimalSeparator`
+- `element/animated-number` — `AnimatedNumber`: rolling digits over static `Intl.NumberFormat` text on a `<data>` root (plain text through SSR, hydration and reduced motion — no layout shift, no flash of `0`); `value` (`null` or non-finite renders `fallback`), `format` (`Intl.NumberFormatOptions` minus two notations; default `{ notation: "standard", maximumFractionDigits: 0 }`), `locale`, `prefix`, `suffix`, `fallback`, `trend`, `digits`, `plugins` (`continuous`). The roll is timed by `pace`; there is no timing prop. `AnimatedNumber.Group` links counters that change together; `useIsSupported` is re-exported. **Optional peer:** `@number-flow/react` — install it or the subpath fails to resolve.
 
 ```tsx
-<AnimatedNumber value={total} springOptions={{ bounce: 0.2 }} />
+<AnimatedNumber value={total} format={{ notation: "compact", maximumFractionDigits: 1 }} />
 ```
 
 ## Stagger entrance
 
-- `motion-primitives/animated-group` — `AnimatedGroup`: staggers children in on mount/update. **Props:** `preset` [fade|slide|scale|blur|blur-slide|zoom|flip|bounce|rotate|swing], `variants` (`{ container, item }`, overrides preset), `as`/`asChild`
+- `effect/animated-list` — `AnimatedList`: animates keyed children entering, leaving and reflowing; `animation` [slide|fade|scale] (default `slide`), `animate` (play the entrance on first mount), `as`, `itemAs`, `layout` [true|position]. Every child needs a stable `key`; a leaver pops out of the flow against the `relative` root. Above 50 children, items render as plain elements with no motion. `block/list` already wraps it.
 
 ```tsx
-<AnimatedGroup preset="blur-slide">
-  {items.map((item) => <Card key={item.id}>{item.label}</Card>)}
-</AnimatedGroup>
+<AnimatedList className="space-y-2">
+  {items.map((item) => <Row key={item.id} item={item} />)}
+</AnimatedList>
 ```
 
 ## Text effects
 
-Per-character/word/line text animation — low-frequency surfaces only (empty states, onboarding, marketing-adjacent copy).
+Per-character/word/line text animation — low-frequency surfaces only (empty states, onboarding, marketing-adjacent copy). Each member renders a `span` by default and takes a string child. `trigger` means one thing across the family: a `false → true` edge replays the effect.
 
-- `motion-primitives/text-effect` — `TextEffect`: staggered reveal; `per` [word|char|line], `preset` [blur|fade-in-blur|scale|fade|slide], `delay`, `trigger`, `onAnimationComplete`
-- `motion-primitives/text-morph` — `TextMorph`: morphs character-by-character between successive `children` string values; `as`, `variants`, `transition`
-- `motion-primitives/text-scramble` — `TextScramble`: scrambles through random characters before resolving; `duration`, `speed`, `characterSet`, `trigger`, `onScrambleComplete`
-- `motion-primitives/text-shimmer` — `TextShimmer`: looping gradient shimmer across the text; `duration`, `spread`
+- `effect/text-effects` — `TextEffect`: staggered reveal; `per` [word|char|line] (default `word`), `animation` [blur|fade-in-blur|scale|fade|slide] (default `fade`), `delay`, `speedReveal`, `speedSegment`, `trigger`, `onAnimationComplete`, `segmentWrapperClassName`. Prefer `per="word"` or `"line"` for long strings (above 50 segments, per-segment motion drops)
+- `effect/text-effects` — `TextMorph`: cross-fades one short string into the next in place; change `children` in place, never force a new `key`
+- `effect/text-effects` — `TextScramble`: decodes a string in from noise; `duration` (default `0.8`), `speed` (default `0.04`), `characterSet`, `trigger`, `onAnimationComplete`
+- `effect/text-effects` — `TextShimmer`: continuous "still working" gradient sweep; `duration` (default `2`), `spread` (default `2`)
+- `effect/text-effects` — `TypingAnimation`: types a string, or cycles `words`; `typeInterval` (default `0.1`), `deleteInterval` (default half `typeInterval`), `startDelay`, `holdDelay` (default `1`), `loop`, `start` [mount|view] (default `view`), `hasCursor` (default `true`), `isCursorBlinking` (default `true`), `cursorStyle` [line|block|underscore]
+- `effect/dia-text-reveal` — `DiaTextReveal`: sweeps a colour band across a line, revealing it; `words` + `loop` rotate several strings, `colors` (band stops only — the text inherits its colour), `duration` (default `1.5`), `delay`, `holdDelay` (default `0.5`), `start` [mount|view|each-view] (default `view`), `hasFixedWidth`. The line is blank until the sweep passes
 
-## Morphing overlays
+## Animated icons
+
+- `effect/icons` — `AnimateIcon` plus 259 lucide-derived animated icons, each exported under its plain name and an `…Icon` alias (`Activity` / `ActivityIcon`, `ArrowDown` / `ArrowDownIcon`, …). Triggers sit on an icon or on an `AnimateIcon` wrapper that drives every icon inside it: `animateOnHover`, `animateOnTap`, `animateOnView` (`animateOnViewMargin`, `animateOnViewOnce`), or the boolean `animate` for an external trigger; `animation` names the variant (`default`, `default-loop`, … per icon), `loop`, `startDelay`, `holdDelay`, `persistOnAnimateEnd`, `completeOnStop`. Icon props: `size`, `label` (an unlabelled icon is `aria-hidden`). `AnimateIcon` drives only icons from this set — wrapping a plain `lucide-react` icon triggers nothing. A static icon is `lucide-react` directly; an icon from a stored name is `element/icon`.
 
-Trigger element morphs its own bounds into the overlay (shared-layout, not a fade) — interruptible mid-animation.
+## Morphing overlays
 
-- `motion-primitives/morphing-dialog` — `MorphingDialog` (root) + `MorphingDialogTrigger`, `MorphingDialogContainer` (portal), `MorphingDialogContent`, `MorphingDialogTitle`, `MorphingDialogSubtitle`, `MorphingDialogDescription` (`disableLayoutAnimation`), `MorphingDialogImage`, `MorphingDialogClose`; root takes `transition`
-- `motion-primitives/morphing-popover` — `MorphingPopover` (`defaultOpen`/`open`/`onOpenChange`, `variants`) + `MorphingPopoverTrigger`, `MorphingPopoverContent`
+The trigger morphs its own bounds into the popup (shared layout on the slow motion step, not a fade); under reduced motion the popup opens on the plain transition. Both are parts of the overlay families in [overlays.md](overlays.md):
 
-```tsx
-<MorphingDialog>
-  <MorphingDialogTrigger>
-    <img src={thumb} alt="" />
-  </MorphingDialogTrigger>
-  <MorphingDialogContainer>
-    <MorphingDialogContent>
-      <MorphingDialogImage src={fullSize} alt="" />
-    </MorphingDialogContent>
-  </MorphingDialogContainer>
-</MorphingDialog>
-```
+- `compound/dialog` — `Dialog.MorphTrigger`, in place of `Dialog.Trigger`; takes no `render` (style it with `className`)
+- `element/popover` — `Popover.MorphTrigger`, in place of `Popover.Trigger`; takes no `render`
 
 ## Panel transitions
 
-Crossfade/slide between sibling panels, or a height-animated reveal. Distinct from the plain shadcn `accordion`/`tabs` subpaths in [layout.md](layout.md)/[navigation.md](navigation.md) — these are the animated variants.
+Swap between sibling panels, or a height-animated reveal.
 
-- `motion-primitives/transition-panel` — `TransitionPanel`: crossfades between `children[activeIndex]`; `variants` (`{ enter, center, exit }`), `transition`
-- `motion-primitives/disclosure` — `Disclosure` (root, `open`/`onOpenChange`) + `DisclosureTrigger`, `DisclosureContent`; `useDisclosure()` for custom triggers
-- `motion-primitives/accordion` — animated `Accordion` (root, `expandedValue`/`onValueChange`, single-expand) + `AccordionItem`, `AccordionTrigger`, `AccordionContent`; `useAccordion()`
-- `animate-ui/components/animate/tabs` — animated `Tabs`: sliding active-tab highlight over the primitive below; `variant` [solid|underline], `size` [sm|md|lg]
+- `effect/transition-panel` — `TransitionPanel` + `TransitionPanel.Panel` (each with a `value`): shows the Panel matching `value` (controlled only — no `defaultValue` or `onValueChange`; an unmatched `value` renders nothing); `animation` [fade|slide|scale] (default `fade`). Slide direction follows Panel order; panels of different heights change the root's height at the swap
+- `compound/tabs` — `Tabs.Contents` settles the panel box to the active panel's height and fades the entering panel in; reach for Tabs rather than pairing a hand-rolled tab strip with `TransitionPanel` ([navigation.md](navigation.md))
+- `compound/accordion` / `element/collapsible` — `Accordion.Panel` and `Collapsible.Panel` open on their own measured height ([layout.md](layout.md))
 
 ## Decorative effects
 
-Pointer-tracked washes and ambient loops — decorative chrome only, never load-bearing content.
+Pointer-tracked washes, sliding highlights and ambient loops — decorative chrome only, never load-bearing content.
 
-- `motion-primitives/spotlight` — `Spotlight`: cursor-following radial glow inside a `position: relative` parent; `size`, `springOptions`
-- `motion-primitives/glow-effect` — `GlowEffect`: animated multi-color glow; `mode` [rotate|pulse|breathe|colorShift|flowHorizontal|static], `colors`, `blur` (preset or px number), `duration`, `scale`
-- `motion-primitives/animated-background` — `AnimatedBackground`: sliding highlight that tracks the active/hovered child (each child needs a `data-id`); `defaultValue`, `onValueChange`, `enableHover`
-- `motion-primitives/infinite-slider` — `InfiniteSlider`: seamless looping marquee; `gap`, `speed`, `speedOnHover`, `direction` [horizontal|vertical], `reverse`
-- `animate-ui/primitives/effects/highlight` — `Highlight`: the sliding-highlight primitive underneath `AnimatedBackground`/animated `Tabs`; `mode` [children|parent], `value`/`defaultValue`/`onValueChange` (controlled or uncontrolled), `hover`, `click`, `transition`, `exitDelay`
+- `effect/spotlight` — `Spotlight`: cursor-following radial glow, first child of a `relative overflow-hidden` parent; `diameter` (px, default `200`), `as` (`span` inside phrasing content). No spring prop — the trail follows `pace`
+- `effect/shine-border` — `ShineBorder`: absolutely-positioned animated gradient border, placed as the direct first child of a `relative overflow-hidden` rounded card; `borderWidth` (px, defaults to `--edge-hairline`), `duration` (seconds, default 14), `colors` (gradient stops, default `["var(--primary)"]`).
+- `effect/glow-effect` — `GlowEffect`: animated multi-colour halo, first child of a `relative` parent with the content in a later `relative` sibling; `animation` [rotate|pulse|breathe|colorShift|flowHorizontal|static] (default `rotate`), `colors`, `blur` [softest|soft|medium|strong|stronger|strongest|none] or a px number (default `medium`), `duration` (default `5`), `scale` (default `1`; raise it to bleed past the parent)
+- `effect/grainient` — `Grainient`: WebGL2 animated grain gradient for a hero or empty-state background; `colors` (three stops, default `GRAINIENT_DEFAULT_COLORS`; token stops follow `.dark`), `timeSpeed` (default `0.25`), `warpSpeed`, `isGrainAnimated`, `maxFps` (default `30`), plus shader tuning (`colorBalance`, `warpStrength`, `warpFrequency`, `warpAmplitude`, `blendAngle`, `blendSoftness`, `rotationAmount`, `noiseScale`, `grainAmount`, `grainScale`, `contrast`, `gamma`, `saturation`, `centerX`, `centerY`, `zoom`). Override its root to `absolute inset-0` inside a `relative` parent; one instance per screen
+- `effect/infinite-slider` — `InfiniteSlider`: seamless looping marquee that pauses on hover and focus within; `gap` (px, default `16`), `speed` (default `100`), `orientation` [horizontal|vertical], `isReversed`, `isPaused`, `as`. Children render twice — give each a stable `key` and keep `id`s and form controls out
+- `effect/highlight` — `Highlight` + `Highlight.Item` (each with a string `value`): one box slides behind the item the host's `value` names (controlled only; `value={null}` shows none); `mode` [children|parent] (`parent` for mixed-size items), `exitDelay` (ms, default `200`), `boundsOffset`, `containerClassName`, `as`; root `className` and `style` paint the box (add `inset-0` in `children` mode). `useHighlightHover(restingValue)` returns `value` plus `getItemProps(id)` for a box that follows the pointer — paint it neutral (`bg-muted`), never the accent
 
-## Dynamic toolbar
+```tsx
+const hover = useHighlightHover(currentPage);
+
+<Highlight value={hover.value} className="inset-0 rounded-md bg-muted">
+  {pages.map((page) => (
+    <Highlight.Item key={page.id} value={page.id} {...hover.getItemProps(page.id)}>
+      <a href={page.href}>{page.label}</a>
+    </Highlight.Item>
+  ))}
+</Highlight>
+```
 
-- `motion-primitives/toolbar-dynamic` — `ToolbarDynamic`: toolbar that expands to a contextual search input; `expandedWidth`, `collapsedWidth`, `placeholder`, `transition`. Ships `ToolbarButton` for the collapsed action icons.
+## Motion-aware slot
 
----
+`Slot` (from `lib/slot`) — the motion-aware `asChild` slot: renders its single child element with the slot's props merged on (classes through `cn`, `style` merged with the slot's values winning, both refs kept), lifting the child onto a motion component so motion props reach a plain element. A non-element child renders nothing. `WithAsChild<Props>` is the matching props shape. Base UI parts compose through their `render` prop instead; `Slot` is for consumers building their own motion children.
+
+```tsx
+<Slot whileHover={{ scale: 1.02 }} className="rounded-md">
+    <a href="/reports">Reports</a>
+</Slot>
+```
+
+## Dynamic toolbar
 
-Two further `animate-ui` subpaths are low-level primitives consumed internally rather than composed directly: `animate-ui/primitives/animate/slot` (an `asChild`-merging `Slot`, the plumbing behind the animated `Tabs`) and `animate-ui/primitives/effects/theme-toggler` (the directional-wipe primitive behind the `theme-toggler` component in [media.md](media.md)).
+No primitive (`dynamic-toolbar`) — a toolbar that expands into a contextual input follows the plain-spec fallback in [index.md](index.md).

package/data/harnesses/code/skills/design/components/navigation.md

@@ -2,28 +2,67 @@
 
 > Generated reference (regen-owned; see [index.md](index.md)). Binds only under `primitives: nurix`.
 
-Components: Breadcrumb, Menubar, Navbar, NavigationMenu, Pagination, Sidebar, SlideOutMenu, Tabs, VerticalIconBar
+Components: Breadcrumb, Menubar, NavigationMenu, Pagination, Sidebar, Tabs, VerticalIconBar
 
-Each imports from its own subpath, with compound members alongside, e.g. `import { Tabs, TabsList, TabsTrigger, TabsContent } from "@nurix/components/compound/tabs"`.
+Each imports from its own subpath as one namespace, with its parts as dotted members, e.g. `import { Tabs } from "@nurix/components/compound/tabs"` then `Tabs.List`, `Tabs.Trigger`, `Tabs.Content`.
 
 ## Sidebar
 
-App sidebar: full shadcn primitives plus an opinionated layer, all from the single `@nurix/components/block/sidebar` subpath.
+Collapsible app shell: the shadcn primitives plus an opinionated kit, all as `Sidebar.*` members of `@nurix/components/block/sidebar`, with `useSidebar` beside it.
 
-**Sub-components:** `SidebarProvider`, `Sidebar` (`side` [left|right], `variant` [sidebar|floating|inset], `collapsible` [offcanvas|icon|none]), `SidebarTrigger`, `SidebarHeader`, `SidebarContent`, `SidebarFooter`, `SidebarGroup`, `SidebarMenu`, `SidebarMenuItem`, `SidebarMenuButton`, `SidebarRail`, `SidebarInset`, `useSidebar`. **Opinionated layer:** `Brand`, `Switcher` (`render` [simple|rich], `options`, `activeId`, `onSelect`), `ItemGroup` (`render` [list|tree|rich], `collapsible`, `compact`, `collapsedLabel` [hide|divider], `items`, `onItemClick`), `UserMenu`, `Callout`, `FileTree`, `SidebarCommandTrigger`.
+**Sub-components:** `Sidebar.Provider` (`defaultOpen`, `open`, `onOpenChange`, `openMobile`, `onOpenMobileChange`, `keyboardShortcut` [default `"b"`, `null` unbinds], `labels`), `Sidebar` (`side` [start|end], `variant` [sidebar|floating|inset], `collapsible` [offcanvas|icon|none], default `offcanvas`), `Sidebar.Trigger`, `.Rail`, `.Inset`, `.Input`, `.Header`, `.Content`, `.Footer`, `.Separator`, `.Group`, `.GroupLabel`, `.GroupAction`, `.GroupContent`, `.Menu`, `.MenuItem`, `.MenuButton`, `.MenuAction` (`isHoverRevealed`), `.MenuBadge`, `.MenuSkeleton` (`hasIcon`), `.MenuSub`, `.MenuSubItem`, `.MenuSubButton`. **Kit:** `Sidebar.Brand` (`logo`, `name`, `caption`, `href`), `Sidebar.Switcher` (`variant` [simple|rich], `side` [bottom|inline-end], `options`, `value`/`defaultValue`/`onValueChange`, `addAction`), `Sidebar.ItemGroup` (`variant` [list|tree|rich], `items`, `isCollapsible`, `hasCollapsibleItems`, `defaultExpandedIds`, `collapsedLabel` [hide|divider], `onShowMore`, `onItemClick`), `Sidebar.UserMenu` (`user`, `menuItems`), `Sidebar.CommandTrigger` (`collapsedTooltip`).
+
+- `useSidebar()` returns `{ state, open, setOpen, openMobile, setOpenMobile, isMobile, toggleSidebar, panelId, labels }` and throws outside `Sidebar.Provider`.
+- Page content is a sibling `Sidebar.Inset`, never a child of `Sidebar`. The sidebar stores nothing — persist open state through `defaultOpen` + `onOpenChange`.
+- A file tree in the nav is `Sidebar.ItemGroup variant="tree"`; a footer card is a `Sidebar.Group` composed inside `Sidebar.Footer`.
 
 ```tsx
-<SidebarProvider>
+<Sidebar.Provider>
   <Sidebar collapsible="icon">
-    <SidebarHeader>
-      <Switcher options={workspaces} />
-    </SidebarHeader>
-    <SidebarContent>
-      <ItemGroup label="Platform" render="tree" items={items} />
-    </SidebarContent>
-    <SidebarFooter>
-      <UserMenu user={user} />
-    </SidebarFooter>
+    <Sidebar.Header>
+      <Sidebar.Switcher options={workspaces} defaultValue={workspaces[0].id} />
+    </Sidebar.Header>
+    <Sidebar.Content>
+      <Sidebar.ItemGroup label="Platform" variant="tree" items={items} />
+    </Sidebar.Content>
+    <Sidebar.Footer>
+      <Sidebar.UserMenu user={user} menuItems={accountActions} />
+    </Sidebar.Footer>
+    <Sidebar.Rail />
   </Sidebar>
-</SidebarProvider>
+  <Sidebar.Inset><Sidebar.Trigger />{children}</Sidebar.Inset>
+</Sidebar.Provider>
 ```
+
+## Pagination
+
+Pager over a page count (`compound/pagination`); `getPageRange(page, pageCount, siblingCount = 1)` returns the page window as numbers and `"ellipsis"` markers.
+
+**Sub-components:** `Pagination.Content`, `.Item`, `.Link` (`value` or `isActive`, `href`), `.Previous`, `.Next`, `.First`, `.Last`, `.Ellipsis`; every control takes `size` [sm|default|lg], `isIconOnly`, `disabled`.
+
+**Props:** `value`/`defaultValue`/`onValueChange(value, details)`, `pageCount`, `labels`
+
+- A link takes `value` (the root holds the page) or `isActive` (a router owns it, with `href`), never both. In value mode the step controls disable at the ends; in router mode pass `disabled` yourself.
+
+```tsx
+<Pagination value={page} pageCount={12} onValueChange={setPage}>
+  <Pagination.Content>
+    <Pagination.Item><Pagination.Previous /></Pagination.Item>
+    {getPageRange(page, 12).map((entry, index) => (
+      <Pagination.Item key={index}>
+        {entry === "ellipsis" ? <Pagination.Ellipsis /> : <Pagination.Link value={entry}>{entry}</Pagination.Link>}
+      </Pagination.Item>
+    ))}
+    <Pagination.Item><Pagination.Next /></Pagination.Item>
+  </Pagination.Content>
+</Pagination>
+```
+
+## Other Components
+
+- `compound/tabs` — `Tabs` with `Tabs.List` (`align` [start|justify], `activateOnFocus`), `Tabs.Trigger`, `Tabs.Content` (`keepMounted`), optional `Tabs.Contents` (height-settling, fading panel box); root `value`/`defaultValue`/`onValueChange`, `variant` [default|underline], `size` [sm|default|lg], `orientation`
+- `compound/breadcrumb` — `Breadcrumb` with `Breadcrumb.Item` (`href`, `render`; the last item always renders as the current page); `maxItems` with `itemsBeforeCollapse`/`itemsAfterCollapse` (default 1 and 2) folds the middle behind an ellipsis menu; `separator`, `labels`
+- `compound/navigation-menu` — `NavigationMenu` with `.List`, `.Item`, `.Trigger`, `.Content`, `.Link` (`isActive`, `closeOnClick`, `render`); a plain link takes `className={navigationMenuTriggerStyle({ size })}`; placement and `hasArrow` sit on the root, beside `orientation` and `labels.navigation`
+- `compound/menubar` — `Menubar` with `.Menu`, `.Trigger`, `.Popup`, `.Item` (fires `onClick`, never `onSelect`), `.LinkItem`, `.CheckboxItem`, `.RadioGroup`/`.RadioItem`, `.Group`, `.Label`, `.Separator`, `.Sub`/`.SubTrigger`/`.SubPopup`, `.Shortcut` (display only, binds no key)
+- `block/vertical-icon-bar` — `VerticalIconBar`: narrow always-icon rail; `items` (`{ value, label, icon, href?, render?, description?, badge?, disabled? }`), `value`/`defaultValue`/`onValueChange`, `width` (default `5rem`), `footer`, `labels.navigation`
+- No nurix primitive: `navbar` (nearest composition `NavigationMenu`) and `stepper` — build both from the `index.md` fallback spec