@moldable-ai/ui 0.2.29 → 0.2.31

package/src/components/ui/menubar.md

@@ -0,0 +1,58 @@
+# Menubar
+
+## Purpose
+
+`Menubar` presents a persistent row of related command menus, such as File,
+Edit, and View. Use it for command families that benefit from repeated
+keyboard access; use `DropdownMenu` for a single contextual action menu.
+
+## Usage
+
+```tsx
+import {
+  Menubar,
+  MenubarContent,
+  MenubarItem,
+  MenubarMenu,
+  MenubarShortcut,
+  MenubarTrigger,
+} from '@moldable-ai/ui'
+
+;<Menubar>
+  <MenubarMenu>
+    <MenubarTrigger className="cursor-pointer">File</MenubarTrigger>
+    <MenubarContent>
+      <MenubarItem onSelect={createDocument}>
+        New document
+        <MenubarShortcut>⌘N</MenubarShortcut>
+      </MenubarItem>
+    </MenubarContent>
+  </MenubarMenu>
+</Menubar>
+```
+
+## API summary
+
+- `Menubar`, `MenubarMenu`, and `MenubarTrigger` form the required shell.
+- `MenubarContent` is portalled and defaults to `align="start"`,
+  `alignOffset={-4}`, and `sideOffset={8}`.
+- `MenubarItem` supports `inset` and
+  `variant="default" | "destructive"`.
+- Checkbox items, radio groups/items, groups, labels, separators, shortcuts,
+  and submenus are exported for structured command sets.
+- `MenubarLabel` and `MenubarSubTrigger` support `inset`.
+- Components otherwise accept the corresponding Radix menubar props.
+
+## Guidance
+
+- Keep top-level trigger labels short and conventional.
+- Use checkbox and radio items for menu-owned state, and `onSelect` for
+  commands.
+- Put destructive commands last or in a separated group; do not rely on color
+  alone to communicate risk.
+- `MenubarShortcut` is display text only and does not register a handler.
+- Radix supplies menu roles, focus movement, typeahead, Escape dismissal, and
+  submenu navigation. Preserve those semantics and give icon-only content an
+  accessible name.
+- Keep submenus shallow and use `Popover` or `Dialog` for arbitrary form
+  controls.

package/src/components/ui/message-scroller-primitive.md

@@ -0,0 +1,70 @@
+# Message Scroller Primitive
+
+## Purpose
+
+`message-scroller-primitive.tsx` is the unstyled React wiring for the
+in-repository transcript controller and scroll-ownership policy. The public
+`MessageScroller*` components wrap this module with layout, button, and
+animation styles; app code should use those wrappers.
+
+## Anatomy
+
+```tsx
+<MessageScroller.Provider autoScroll>
+  <MessageScroller.Root>
+    <MessageScroller.Viewport>
+      <MessageScroller.Content>
+        <MessageScroller.Item messageId="turn-1" scrollAnchor>
+          {/* message */}
+        </MessageScroller.Item>
+      </MessageScroller.Content>
+    </MessageScroller.Viewport>
+    <MessageScroller.Button direction="end" />
+  </MessageScroller.Root>
+</MessageScroller.Provider>
+```
+
+This local-only example uses the `MessageScroller` object exported by the
+primitive module. `Provider` must wrap every root, item, button, and hook.
+
+## Primitive contract
+
+- Provider defaults: `autoScroll={false}`, `defaultScrollPosition="end"`,
+  `scrollEdgeThreshold={8}`, `scrollPreviousItemPeek={64}`, and
+  `scrollMargin={0}`. Changing `defaultScrollPosition` resets the one-time
+  initial-position decision for the next content mutation.
+- `Viewport` forwards scroll, wheel, touch, and scroll-key events after
+  notifying the controller. It defaults to a focusable messages region and
+  observes viewport size changes.
+- `Content` defaults to an additions-only live log, observes direct child
+  mutations and size changes, and appends a hidden internal spacer.
+- `Item` registers `messageId` elements and writes anchor data used for
+  initial placement, new-turn anchoring, targeted scrolling, and visibility.
+- `Button` supports `direction="start" | "end"`, `behavior`, and a `render`
+  element or render function. Defaults are end, smooth, and `type="button"`.
+  Inactive buttons are inert with `tabIndex={-1}`; preventing the click event's
+  default also prevents the scroll command.
+
+## Controller and policy behavior
+
+The controller is the sole owner of programmatic transcript movement. The
+policy distinguishes following the end, free reading, an anchored turn, and a
+settling commanded jump. Wheel, touch, scroll-key, scrollbar, or other motion
+away from a declared target gives control to the reader immediately.
+
+It also:
+
+- keeps a followed end pinned during growth;
+- reanchors a streaming turn after resize;
+- preserves the first visible row when older items are prepended;
+- restores a stable visible leaf when content above collapses;
+- grows the internal spacer so late items can reach the requested alignment;
+- exposes edge state as `data-scrollable` and active programmatic movement as
+  `data-autoscrolling` on root and viewport;
+- observes visibility only while `useMessageScrollerVisibility` has
+  subscribers.
+
+For finer reading-position stability inside a complex item, mark stable
+descendants with `data-message-scroll-anchor`. Do not manipulate the
+controller, spacer, data attributes, or scroll position from a competing
+effect; extend the wrapper API when new behavior is required.

package/src/components/ui/message-scroller.md

@@ -0,0 +1,86 @@
+# Message Scroller
+
+## Purpose
+
+`MessageScroller` is the styled, public transcript scroller. It keeps streamed
+content stable, preserves the reader's position when history is prepended or
+content above changes size, supports turn anchors, and exposes jump and
+visibility state.
+
+## Usage
+
+```tsx
+import {
+  MessageScroller,
+  MessageScrollerButton,
+  MessageScrollerContent,
+  MessageScrollerItem,
+  MessageScrollerProvider,
+  MessageScrollerViewport,
+} from '@moldable-ai/ui'
+
+;<MessageScrollerProvider autoScroll defaultScrollPosition="end">
+  <MessageScroller>
+    <MessageScrollerViewport>
+      <MessageScrollerContent className="gap-3 p-3">
+        {messages.map((message) => (
+          <MessageScrollerItem
+            key={message.id}
+            messageId={message.id}
+            scrollAnchor={message.role === 'user'}
+          >
+            {renderMessage(message)}
+          </MessageScrollerItem>
+        ))}
+      </MessageScrollerContent>
+    </MessageScrollerViewport>
+    <MessageScrollerButton />
+  </MessageScroller>
+</MessageScrollerProvider>
+```
+
+## API summary
+
+- `MessageScrollerProvider` is required. Defaults are `autoScroll={false}`,
+  `defaultScrollPosition="end"`, `scrollEdgeThreshold={8}`,
+  `scrollPreviousItemPeek={64}`, and `scrollMargin={0}`.
+- Initial position can be `start`, `end`, or `last-anchor`. The last option
+  anchors the newest marked turn only when enough transcript follows it;
+  otherwise it lands at the end.
+- `MessageScrollerViewport` is a focusable `role="region"` labelled
+  “Messages” by default. `preserveScrollOnPrepend` defaults to true.
+- `MessageScrollerContent` defaults to `role="log"` and
+  `aria-relevant="additions"`. It accepts `spacerClassName` for the internal
+  positioning spacer.
+- `MessageScrollerItem` accepts `messageId` and `scrollAnchor` (false by
+  default). IDs enable targeted scrolling and visibility reporting; mark the
+  start of each new turn as an anchor.
+- `MessageScrollerButton` defaults to an end jump with smooth behavior,
+  `variant="secondary"`, and `size="icon-sm"`. It becomes inert and leaves
+  the tab order when that edge is not scrollable. `direction="start"` creates
+  the corresponding top jump.
+
+## Hooks and behavior
+
+- `useMessageScroller()` returns `scrollToStart`, `scrollToEnd`, and
+  `scrollToMessage`. Targeted scrolls accept `align`, `behavior`, and
+  `scrollMargin`; alignment defaults to `start` and behavior to `auto`.
+- `useMessageScrollerScrollable()` returns `{ start, end }`.
+- `useMessageScrollerVisibility()` returns `currentAnchorId` and ordered
+  `visibleMessageIds`.
+- Hooks must be descendants of the provider.
+- Reader input takes ownership immediately. With `autoScroll`, content follows
+  the end only while follow mode is active; a newly appended turn anchor is
+  held near the top with the configured previous-item peek.
+
+## Guidance
+
+- Give every navigable item a stable `messageId`; do not use an array index.
+- Mark only meaningful turn starts as `scrollAnchor`.
+- Keep one viewport as the owning vertical scroll region and give its flex
+  ancestors `min-h-0`.
+- Preserve the default region label or supply a more specific `aria-label`.
+- Keep the content's log semantics and busy state accurate while streaming or
+  loading history.
+- Do not add a second effect that writes `scrollTop`; all movement must go
+  through the scroller API so it cannot fight the reader.

package/src/components/ui/navigation-button-group.md

@@ -17,9 +17,10 @@ consistent compact treatment.
 - `canGoBack` and `canGoForward` disable unavailable directions.
 - `onBack` and `onForward` perform caller-owned navigation.
 - `backLabel` and `forwardLabel` customize accessible names.
-- `size` accepts the `IconButton` size scale.
-- `variant` is `ghost` or `outline`.
-- Native `ButtonGroup` props apply to the group.
+- `size` accepts the `IconButton` size scale and defaults to `sm`.
+- `variant` is `ghost` or `outline` and defaults to `ghost`.
+- Remaining `ButtonGroup` props apply to the root except `children` and
+  `orientation`; the component owns two buttons in a horizontal group.
 
 ## Keyboard and accessibility
 

package/src/components/ui/navigation-menu.md

@@ -0,0 +1,52 @@
+# Navigation Menu
+
+`NavigationMenu` presents a compact row of destinations, with optional
+disclosure panels for grouped links. Use it for navigation, not for commands
+or form actions.
+
+```tsx
+import {
+  NavigationMenu,
+  NavigationMenuContent,
+  NavigationMenuItem,
+  NavigationMenuLink,
+  NavigationMenuList,
+  NavigationMenuTrigger,
+} from '@moldable-ai/ui'
+
+;<NavigationMenu viewport={false}>
+  <NavigationMenuList>
+    <NavigationMenuItem>
+      <NavigationMenuTrigger>Projects</NavigationMenuTrigger>
+      <NavigationMenuContent>
+        <NavigationMenuLink href="/projects/recent" active>
+          Recent
+        </NavigationMenuLink>
+        <NavigationMenuLink href="/projects/shared">Shared</NavigationMenuLink>
+      </NavigationMenuContent>
+    </NavigationMenuItem>
+  </NavigationMenuList>
+</NavigationMenu>
+```
+
+## API
+
+- `NavigationMenu` exposes the Radix root props plus `viewport`. The shared
+  viewport is rendered by default; set `viewport={false}` for a panel attached
+  to each item.
+- `NavigationMenuList`, `NavigationMenuItem`, `NavigationMenuTrigger`,
+  `NavigationMenuContent`, `NavigationMenuLink`, and
+  `NavigationMenuIndicator` expose their corresponding Radix props.
+- `NavigationMenuLink` accepts `active` for the current destination.
+- `NavigationMenuViewport` and `navigationMenuTriggerStyle` are exported for
+  custom composition.
+
+## Quality and accessibility
+
+- Use real destinations and preserve link semantics with `href`.
+- Give every trigger and icon-only link an accessible name.
+- Mark only the current destination active.
+- Keep labels short and disclosure panels easy to scan.
+- Preserve the keyboard and focus behavior supplied by Radix; do not make
+  essential destinations available only on pointer hover.
+- Use `Menubar`, `DropdownMenu`, or ordinary buttons for actions.

package/src/components/ui/number-input.md

@@ -17,3 +17,11 @@ Use in inspectors and settings where the numeric value matters. Use `Slider`
 when relative adjustment matters more than exact entry. Always supply a visible
 label or `aria-label`. Treat `null` as empty input and validate domain-specific
 constraints outside the component.
+
+`value`/`onValueChange` provide controlled state; `defaultValue` provides
+uncontrolled initial state. `variant` is `default` or `filled`, and `size` is
+`sm`, `default`, or `lg`. Both default to `default`. Steppers are shown by
+default; set `steppers={false}` to hide them. They use a finite numeric `step`
+(falling back to `1`), start an empty value from zero, and clamp their result
+to finite `min`/`max` values. Typed input still relies on native numeric
+validity and caller validation.

package/src/components/ui/pagination.md

@@ -0,0 +1,51 @@
+# Pagination
+
+`Pagination` links between pages in a bounded result set.
+
+```tsx
+import {
+  Pagination,
+  PaginationContent,
+  PaginationItem,
+  PaginationLink,
+  PaginationNext,
+  PaginationPrevious,
+} from '@moldable-ai/ui'
+
+;<Pagination>
+  <PaginationContent>
+    <PaginationItem>
+      <PaginationPrevious href="?page=1" />
+    </PaginationItem>
+    <PaginationItem>
+      <PaginationLink href="?page=2" isActive>
+        2
+      </PaginationLink>
+    </PaginationItem>
+    <PaginationItem>
+      <PaginationNext href="?page=3" />
+    </PaginationItem>
+  </PaginationContent>
+</Pagination>
+```
+
+## API
+
+- `Pagination` renders a centered `nav` named “pagination”.
+- `PaginationContent` and `PaginationItem` render the list structure.
+- `PaginationLink` renders an anchor. `isActive` applies the outlined state
+  and `aria-current="page"`; `size` uses the shared button size scale.
+- `PaginationPrevious` and `PaginationNext` provide responsive text and
+  accessible labels.
+- `PaginationEllipsis` is a decorative gap marker, not a link.
+
+## Quality and accessibility
+
+- Supply a real `href` for every available page and keep the current location
+  marked with `isActive`.
+- Keep page order stable and show enough neighboring pages to retain context.
+- At a range boundary, omit the unavailable link or implement
+  `aria-disabled`, remove it from Tab order, and prevent navigation; anchors
+  do not support the native `disabled` attribute.
+- Do not use pagination for infinite loading or a small list that fits in one
+  view.

package/src/components/ui/panel.md

@@ -9,3 +9,9 @@ bounded content groups inside a pane.
 
 The group and its containing shell need a definite height. Long content belongs
 in `PanelContent`, and chat-safe padding belongs on that scrolling region.
+
+`PanelGroup` defaults to horizontal and accepts `orientation="vertical"`.
+`Panel` supports `surface="default" | "muted" | "sidebar" | "transparent"`
+and `border="none" | "all" | "inline" | "block"`. Surface defaults to
+`default`; border defaults to `none`. The structural components otherwise
+accept native props for their rendered `section`, `header`, `div`, or `footer`.

package/src/components/ui/popover.md

@@ -21,11 +21,14 @@ Use `Popover` for a small, interactive surface anchored to a control. Use
 
 Sizes are `content`, `sm`, `default`, and `lg`. Content is capped to the
 collision-aware available width and height and scrolls when necessary.
-`material="regular"` is the standard temporary overlay. Use `clear` only above
-media or a richly colored canvas where the stronger sampled effect has a clear
-layering purpose.
+Content defaults to `size="default"`, `align="center"`, `sideOffset={4}`, and
+`material="regular"`. The `material` prop accepts every `MaterialVariant`:
+the five named thicknesses plus the `regular` and `clear` compatibility
+aliases. Use a thin surface only where the content behind it keeps text and
+controls legible.
 
-`PopoverClose`, `PopoverPortal`, and `PopoverArrow` are available when the
-composition needs them. Provide an accessible name on an icon-only close
-action. Keep required instructions and critical actions discoverable without
-hover.
+`PopoverContent` is already portalled. `PopoverAnchor`, `PopoverClose`, and
+`PopoverArrow` are available when the composition needs them;
+`PopoverPortal` is exported for custom primitive composition. Provide an
+accessible name on an icon-only trigger or close action. Keep required
+instructions and critical actions discoverable without hover.

package/src/components/ui/progress.md

@@ -0,0 +1,31 @@
+# Progress
+
+`Progress` shows determinate completion for an operation. The current visual
+track expects `value` to be a percentage from `0` to `100`.
+
+```tsx
+import { Progress } from '@moldable-ai/ui'
+
+;<div>
+  <p id="sync-progress">Syncing changes: {percent}%</p>
+  <Progress aria-labelledby="sync-progress" value={percent} />
+</div>
+```
+
+## API
+
+- `Progress` accepts the Radix progress root props and `className`.
+- `value` controls the indicator transform; omitted or zero values render an
+  empty track.
+- The track and indicator use the shared primary color tokens.
+
+## Quality and accessibility
+
+- Clamp the supplied percentage to `0–100`.
+- Give the progress bar an accessible name with `aria-label` or
+  `aria-labelledby`.
+- Include the exact percentage in nearby text when users need it announced or
+  compared.
+- Use `Spinner` when duration or completion cannot be estimated.
+- Remove the progress bar or replace it with a clear completion state when the
+  operation finishes.

package/src/components/ui/radio-group.md

@@ -0,0 +1,36 @@
+# Radio Group
+
+`RadioGroup` lets a user choose one value from a visible set of mutually
+exclusive options.
+
+```tsx
+import { Label, RadioGroup, RadioGroupItem } from '@moldable-ai/ui'
+
+;<RadioGroup defaultValue="normal" aria-label="Priority">
+  <div className="flex items-center gap-2">
+    <RadioGroupItem id="priority-normal" value="normal" />
+    <Label htmlFor="priority-normal">Normal</Label>
+  </div>
+  <div className="flex items-center gap-2">
+    <RadioGroupItem id="priority-high" value="high" />
+    <Label htmlFor="priority-high">High</Label>
+  </div>
+</RadioGroup>
+```
+
+## API
+
+- `RadioGroup` exposes the Radix root props, including controlled `value` and
+  `onValueChange`, uncontrolled `defaultValue`, `name`, `required`, and
+  `disabled`.
+- `RadioGroupItem` requires a unique `value` and exposes the Radix item props.
+- The root lays options out as a grid; use `className` to change the layout.
+
+## Quality and accessibility
+
+- Give the group a visible label, `aria-label`, or `aria-labelledby`.
+- Connect every item to a concise text label with matching `id` and `htmlFor`.
+- Use a stable default only when one option is genuinely preferred.
+- Show validation in text and apply `aria-invalid` when the choice is invalid.
+- Use `Checkbox` for independent choices and `ToggleGroup` for compact view
+  modes rather than form options.

package/src/components/ui/resizable.md

@@ -35,7 +35,8 @@ Use `orientation="vertical"` for editor/results splits. Each panel should establ
 ## API summary
 
 - `ResizablePanelGroup`: wraps `react-resizable-panels` `Group`; `orientation` is `"horizontal"` or `"vertical"` and defaults upstream to horizontal.
-- `ResizablePanel`: wraps `Panel` and accepts its sizing, collapse, callback, id, and ref props.
+- `ResizablePanel`: wraps the upstream `Panel` and accepts its sizing,
+  collapse, callback, id, `elementRef`, and imperative `panelRef` props.
 - `ResizablePanel` also accepts `groupResizeBehavior` for compatibility, but the current wrapper intentionally does not forward or act on it.
 - `ResizableHandle`: wraps `Separator`; `withHandle` adds a visible grip.
 - All parts accept `className` where supported by their underlying primitive.

package/src/components/ui/scroll-area.md

@@ -32,12 +32,14 @@ configuration.
 
 ## API summary
 
-- `ScrollArea`: Radix Scroll Area root with a full-size viewport, vertical `ScrollBar`, and corner.
+- `ScrollArea`: Radix Scroll Area root with a full-size viewport and the
+  scrollbar configuration selected by `scrollbars`.
 - Accepts Radix root props, forwarded `ref`, and `className`.
 - `scrollbars`: `vertical`, `horizontal`, `both`, or `none`.
 - `viewportClassName`: styles the actual scrolling viewport.
 - `safeBottom`: adds the shared chat-safe padding to the viewport exactly once.
 - `ScrollBar`: exported scrollbar primitive with `orientation="vertical" | "horizontal"`; defaults to vertical.
+- A corner is rendered only when both scrollbars are enabled.
 - The root’s direct children are rendered inside the viewport.
 - The viewport supplies focus-visible outline and ring treatment.
 

package/src/components/ui/search-field.md

@@ -19,7 +19,12 @@ import { SearchField } from '@moldable-ai/ui'
 />
 ```
 
-Use `value`/`onValueChange` for a controlled field or `defaultValue` for an uncontrolled field. `variant` is `default` or `filled`; `density` is `compact`, `default`, or `comfortable`. `clearable` defaults to true. Escape and the clear action empty a non-empty field, refocus it, and call `onClear`.
+Use `value`/`onValueChange` for a controlled field or `defaultValue` for an
+uncontrolled field. `variant` is `default` or `filled`; `density` is `compact`,
+`default`, or `comfortable`. `controlSize` accepts `mini`, `small`, `medium`,
+`large`, or `xl` and overrides the size token derived from density. `clearable`
+defaults to true. Escape and the clear action empty a non-empty field, refocus
+it, and call `onClear`.
 
 ## Quality bar
 

package/src/components/ui/segmented-control.md

@@ -22,7 +22,12 @@ import { SegmentedControl, SegmentedControlItem } from '@moldable-ai/ui'
 </SegmentedControl>
 ```
 
-The root supports controlled `value`/`onValueChange` and uncontrolled `defaultValue`. `variant` is `muted` or `outline`; `density` is `compact`, `default`, or `comfortable`; `fullWidth` lets each item share the available width.
+The root supports controlled `value`/`onValueChange` and uncontrolled
+`defaultValue`. `variant` is `muted` or `outline`; `density` is `compact`,
+`default`, or `comfortable`; and `orientation` defaults to `horizontal`.
+`controlSize` accepts `mini`, `small`, `medium`, `large`, or `xl` and overrides
+the size token derived from density. `fullWidth` lets each item share the
+available width.
 
 ## Quality bar
 

package/src/components/ui/separator.md

@@ -0,0 +1,35 @@
+# Separator
+
+`Separator` draws a semantic-token divider between related regions. It is
+decorative by default.
+
+```tsx
+import { Separator } from '@moldable-ai/ui'
+
+;<section>
+  <h2>Workspace</h2>
+  <Separator className="my-3" />
+  <div className="flex h-8 items-center gap-3">
+    <span>Local</span>
+    <Separator orientation="vertical" />
+    <span>Synced</span>
+  </div>
+</section>
+```
+
+## API
+
+- `orientation` is `horizontal` by default and also accepts `vertical`.
+- `decorative` defaults to `true`. Set `decorative={false}` when the divider
+  represents a meaningful structural boundary.
+- Other Radix separator props and `className` pass through.
+
+## Quality and accessibility
+
+- Prefer spacing alone when a line does not clarify grouping.
+- Keep decorative separators out of the accessibility tree with the default
+  behavior.
+- Use a non-decorative separator sparingly; headings and landmarks usually
+  communicate structure more clearly.
+- Give a vertical separator a parent with an explicit height because it uses
+  the full available height.

package/src/components/ui/sidebar.md

@@ -55,7 +55,9 @@ import {
 </SidebarProvider>
 ```
 
-Keep each menu item’s icon and last text span direct children of `SidebarMenuButton`; the component uses that shape for icon sizing and text truncation.
+Keep each menu item’s icon and last text span direct children of
+`SidebarMenuButton`; the component uses that shape for icon sizing, active
+icon tint, and text truncation.
 
 ## API summary
 
@@ -63,7 +65,7 @@ Keep each menu item’s icon and last text span direct children of `SidebarMenuB
 
 - `SidebarProvider`: required context. Supports uncontrolled `defaultOpen`, controlled `open`/`onOpenChange`, and CSS variable overrides through `style`.
 - `useSidebar()`: returns `state`, `open`, `setOpen`, `openMobile`, `setOpenMobile`, `isMobile`, and `toggleSidebar`.
-- `Sidebar`: `side="left" | "right"`, `variant="sidebar" | "floating" | "inset"`, and `collapsible="offcanvas" | "icon" | "none"`.
+- `Sidebar`: `side="left" | "right"`, `variant="sidebar" | "floating" | "inset"`, `sidebarStyle="platform" | "floating" | "edge-to-edge"`, and `collapsible="offcanvas" | "icon" | "none"`.
 - `SidebarInset`: main content surface paired with the sidebar.
 - `SidebarTrigger`: compact toggle button.
 - `SidebarRail`: pointer target along the sidebar edge.
@@ -77,7 +79,7 @@ Keep each menu item’s icon and last text span direct children of `SidebarMenuB
 ### Menus
 
 - `SidebarMenu` and `SidebarMenuItem` provide list structure.
-- `SidebarMenuButton`: `isActive`, `variant="default" | "outline"`, `size="default" | "sm" | "lg"`, optional `asChild`, and `tooltip`.
+- `SidebarMenuButton`: `isActive`, `variant="default" | "outline"`, `size="default" | "sm" | "lg"`, optional `asChild`, and `tooltip`. Active state applies the semantic selection fill and foreground to its direct icon and text.
 - `SidebarMenuAction`: optional `asChild` and `showOnHover`.
 - `SidebarMenuBadge`: compact trailing count.
 - `SidebarMenuSkeleton`: optional `showIcon`.
@@ -111,3 +113,18 @@ Override the shell for the embedded full-height environment with `h-full min-h-0
 The built-in Command/Ctrl+B shortcut must not conflict with editor-local bold formatting or another essential command in the same context. If it does, control sidebar state elsewhere or revisit the shortcut at the package level.
 
 Use semantic `sidebar-*` tokens already provided by the component. In an object browser, post the active connection, collection, or selected object to desktop chat instructions and expose frequent switches through app commands.
+
+### Sidebar style selection
+
+Choose the visual anatomy independently from the application's base platform:
+
+- `edge-to-edge` is the default.
+- `floating` uses the macOS inset, material-backed shell and forces the
+  component's resolved variant to `floating`.
+- `edge-to-edge` uses the macOS joined window/sidebar anatomy and forces the
+  resolved variant to `sidebar`.
+  It has no independent fill, blur, shadow, or internal divider and reveals
+  the app/window background beneath it.
+- `platform` follows the selected platform pack and preserves the existing `variant` behavior.
+
+Set `sidebarStyle` on `ThemeProvider` for the whole application, or on an individual `Sidebar` for a local override. Apps and components must use these semantic names and the stable `--m-ui-sidebar-*` roles rather than importing versioned source values.

package/src/components/ui/skeleton.md

@@ -0,0 +1,36 @@
+# Skeleton
+
+## Purpose
+
+`Skeleton` is a neutral, pulsing placeholder for content whose shape is known
+while its data is loading. Size it to approximate the final content so the
+layout remains stable.
+
+## Usage
+
+```tsx
+import { Skeleton } from '@moldable-ai/ui'
+
+;<div role="status" aria-busy="true">
+  <span className="sr-only">Loading project</span>
+  <Skeleton className="h-5 w-40" />
+  <Skeleton className="mt-3 h-20 w-full" />
+</div>
+```
+
+## API
+
+- Accepts native `div` props and `className`.
+- Uses the semantic accent surface, the shared control radius, and a pulse
+  animation by default.
+- Has no size or visual variants; set dimensions and layout with `className`.
+- Exports `Skeleton`.
+
+## Guidance
+
+- Match the number and approximate dimensions of the content being replaced.
+- Put loading semantics and concise screen-reader status text on the containing
+  region.
+- Keep skeletons non-interactive and remove them when the content resolves.
+- Do not add a separate accessible name to every placeholder or use skeletons
+  for errors and empty states.