@oxy.so/bloom 6.4.0 → 7.0.0

package/README.md

@@ -20,7 +20,7 @@
 
 ### What it is
 
-Components, hooks and design tokens published as `@oxy.so/bloom` across 168 subpath exports, shipped as `src` for Metro and as compiled CommonJS and ESM for everyone else. Web builds resolve platform forks automatically through export conditions, so a `.web.tsx` fork never reaches a native bundle.
+Components, hooks and design tokens published as `@oxy.so/bloom` through component subpath exports, shipped as `src` for Metro and as compiled CommonJS and ESM for everyone else. Web builds resolve platform forks automatically through export conditions, so a `.web.tsx` fork never reaches a native bundle.
 
 Styling is NativeWind classes throughout. There are no colour props and no wrapper components to theme a button, because a second way to set a colour is a second thing that can disagree.
 
@@ -151,7 +151,7 @@ Every palette is generated from a single seed colour by a dependency free colour
 
 ## Components
 
-Bloom publishes 168 subpath exports. Importing from the subpath rather than the root keeps a bundle to what it actually renders.
+Bloom publishes each component family through a subpath export. Importing from the subpath rather than the root keeps a bundle to what it actually renders.
 
 Icons go one step further: every glyph is its own subpath, `@oxy.so/bloom/icons/<RiName>`. Metro does not tree-shake, so the flat `@oxy.so/bloom/icons` barrel ships all 480 glyphs to any app that names one — see [icons](./docs/icons.mdx) for the measurement and when to reach for which import. The barrel keeps working unchanged — it stays an exact `exports` key, and an exact key beats a pattern everywhere.
 
@@ -163,7 +163,7 @@ Icons go one step further: every glyph is its own subpath, `@oxy.so/bloom/icons/
 | Actions | `button`, `button-group`, `social-button`, `fab`, `frosted-icon-button`, `pressable-scale`, `subtle-hover` |
 | Forms | `text-field`, `textarea`, `phone-input`, `input-otp`, `field`, `input-group`, `label`, `select`, `command`, `checkbox`, `radio`, `switch`, `slider`, `segmented-control`, `search`, `date-picker`, `file-upload`, `auth-card`, `stepper`, `rating`, `wizard` |
 | Layout and lists | `grid`, `list`, `scroll`, `settings-list`, `card`, `cover-header`, `accordion`, `aspect-ratio`, `divider`, `item`, `carousel` |
-| Data and charts | `table`, `data-table`, `chart-cards`, `stat-cards`, `calendar`, `composition-bar`, `dot-grid-meter`, `stat-bar`, `activity-heatmap`, `recent-hires-card`, `patient-info-card`, `important-alerts-card`, `agent-limits-card`, `ai-profile-card` |
+| Data and charts | `table`, `data-table`, `chart-cards`, `stat-cards`, `calendar`, `composition-bar`, `stat-bar`, `activity-heatmap`, `recent-hires-card`, `patient-info-card`, `important-alerts-card`, `agent-limits-card`, `ai-profile-card` |
 | Music and media | `media-card`, `media-controls`, `media-header`, `media-player`, `media-shelf`, `track-list`, `queue-panel`, `lyrics`, `music-library`, `creator-studio`, `sortable-media` |
 | Housing | `home-search`, `listing-actions`, `listing-editor`, `offering-badge`, `place-reviews`, `property-insights`, `tenancy`, `eviction` |
 | Stays and booking | `listing-card`, `listing-details`, `stay-search`, `stay-filters`, `booking`, `category-bar`, `map-marker` |

package/docs/adoption-matrix.mdx

@@ -32,12 +32,12 @@ The classification is an EQUALITY in `src/__tests__/adoption-matrix.test.ts`, no
 
 ## Totals
 
-- **208 families** in `src/`, **206** published (a subpath, the root barrel, or both). **41** carry a web fork.
+- **211 families** in `src/`, **209** published (a subpath, the root barrel, or both). **44** carry a web fork.
 - Docs, stories and suites are gated as a standard by `src/__tests__/family-coverage.test.ts`; the per-family counts are in the table below.
 
 | contract | applies to | reads | delegated | n/a¹ | adaptation |
 | --- | --- | --- | --- | --- | --- |
-| Field membership | 47 | 21 | 0 | 21 | 5 |
+| Field membership | 48 | 22 | 0 | 21 | 5 |
 | Control presentation | 42 | 39 | 1 | 2 | 0 |
 | Trigger composition | 10 | 8 | 0 | 2 | 0 |
 | Controlled / uncontrolled state | 53 | 44 | 1 | 1 | 7 |
@@ -113,7 +113,9 @@ The classification is an EQUALITY in `src/__tests__/adoption-matrix.test.ts`, no
 | `activity-heatmap` | `@oxy.so/bloom/activity-heatmap` + barrel | universal | `activity-heatmap.mdx` | yes | 1 |  |  |  |  |
 | `address` | `@oxy.so/bloom/address` + barrel | universal | `address.mdx` | yes | 2 | n/a¹ |  |  |  |
 | `admonition` | `@oxy.so/bloom/admonition` + barrel | universal | `admonition.mdx` | yes | 1 |  |  |  |  |
+| `agent-avatar` | `@oxy.so/bloom/agent-avatar` + barrel | universal | `agent-avatar.mdx` | yes | 9 |  |  |  |  |
 | `agent-chat` | `@oxy.so/bloom/agent-chat` + barrel | web fork | `agent-chat.mdx` | yes | 3 | n/a¹ |  |  | reads |
+| `agent-creator` | `@oxy.so/bloom/agent-creator` + barrel | web fork | `agent-creator.mdx` | yes | 4 | reads |  |  |  |
 | `agent-limits-card` | `@oxy.so/bloom/agent-limits-card` + barrel | universal | `agent-limits-card.mdx` | yes | 2 |  |  |  | reads |
 | `agent-log` | `@oxy.so/bloom/agent-log` + barrel | universal | `agent-log.mdx` | yes | 1 |  |  |  |  |
 | `agent-progress` | `@oxy.so/bloom/agent-progress` + barrel | universal | `agent-progress.mdx` | yes | 2 |  |  |  | reads |
@@ -132,7 +134,7 @@ The classification is an EQUALITY in `src/__tests__/adoption-matrix.test.ts`, no
 | `badge` | `@oxy.so/bloom/badge` + barrel | universal | `badge.mdx` | yes | 2 |  | reads |  |  |
 | `booking` | `@oxy.so/bloom/booking` + barrel | universal | `booking.mdx` | yes | 5 |  |  |  | reads |
 | `bottom-bar` | `@oxy.so/bloom/bottom-bar` + barrel | web fork | `bottom-bar.mdx` | yes | 2 |  |  |  |  |
-| `bottom-sheet` | `@oxy.so/bloom/bottom-sheet` + barrel | web fork | `bottom-sheet.mdx` | yes | 7 |  |  |  |  |
+| `bottom-sheet` | `@oxy.so/bloom/bottom-sheet` + barrel | web fork | `bottom-sheet.mdx` | yes | 8 |  |  |  |  |
 | `breadcrumb` | `@oxy.so/bloom/breadcrumb` + barrel | universal | `breadcrumb.mdx` | yes | 2 |  |  |  |  |
 | `button` | `@oxy.so/bloom/button` + barrel | web fork | `button.mdx` | yes | 40 |  | reads | n/a¹ |  |
 | `button-group` | `@oxy.so/bloom/button-group` + barrel | web fork | `button-group.mdx` | yes | 8 |  | reads |  |  |
@@ -144,7 +146,7 @@ The classification is an EQUALITY in `src/__tests__/adoption-matrix.test.ts`, no
 | `carrier-quote` | `@oxy.so/bloom/carrier-quote` + barrel | universal | `carrier-quote.mdx` | yes | 2 | n/a¹ |  |  | reads |
 | `cart-panel` | `@oxy.so/bloom/cart-panel` + barrel | universal | `cart-panel.mdx` | yes | 1 |  |  |  |  |
 | `category-bar` | `@oxy.so/bloom/category-bar` + barrel | universal | `category-bar.mdx` | yes | 3 |  |  |  |  |
-| `chart-cards` | `@oxy.so/bloom/chart-cards` + barrel | universal | `chart-cards.mdx` | yes | 34 |  |  |  | **adaptation** |
+| `chart-cards` | `@oxy.so/bloom/chart-cards` + barrel | universal | `chart-cards.mdx` | yes | 35 |  |  |  | **adaptation** |
 | `chat-composer` | `@oxy.so/bloom/chat-composer` + barrel | web fork | `chat-composer.mdx` | yes | 4 | n/a¹ | reads |  | reads |
 | `chat-indicators` | `@oxy.so/bloom/chat-indicators` + barrel | universal | `chat-indicators.mdx` | yes | 2 |  |  |  |  |
 | `chat-list` | `@oxy.so/bloom/chat-list` + barrel | universal | `chat-list.mdx` | yes | 3 | n/a¹ |  |  | **adaptation** |
@@ -162,24 +164,23 @@ The classification is an EQUALITY in `src/__tests__/adoption-matrix.test.ts`, no
 | `connection-status` | `@oxy.so/bloom/connection-status` + barrel | web fork | `connection-status.mdx` | yes | 1 |  |  |  |  |
 | `contact-card` | `@oxy.so/bloom/contact-card` + barrel | universal | `contact-card.mdx` | yes | 2 |  |  |  |  |
 | `content-panel` | `@oxy.so/bloom/content-panel` + barrel | web fork | `content-panel.mdx` | yes | 8 |  |  |  |  |
-| `context-menu` | `@oxy.so/bloom/context-menu` + barrel | web fork | `context-menu.mdx` | yes | 5 |  |  | reads |  |
+| `context-menu` | `@oxy.so/bloom/context-menu` + barrel | web fork | `context-menu.mdx` | yes | 6 |  |  | reads |  |
 | `cover-header` | `@oxy.so/bloom/cover-header` + barrel | universal | `cover-header.mdx` | yes | 1 |  |  |  |  |
 | `creator-studio` | `@oxy.so/bloom/creator-studio` + barrel | universal | `creator-studio.mdx` | yes | 4 |  | n/a¹ |  | **adaptation** |
 | `data-table` | `@oxy.so/bloom/data-table` + barrel | universal | `data-table.mdx` | yes | 4 |  | reads |  | reads |
 | `date-picker` | `@oxy.so/bloom/date-picker` + barrel | universal | `date-picker.mdx` | yes | 5 | reads | reads |  | reads |
 | `delivery-slot` | `@oxy.so/bloom/delivery-slot` + barrel | universal | `delivery-slot.mdx` | yes | 2 | reads |  |  |  |
-| `design-tokens` | `@oxy.so/bloom/design-tokens` + barrel | universal | `design-tokens.mdx` | yes | 5 |  |  |  |  |
-| `dialog` | `@oxy.so/bloom/dialog` + barrel | web fork | `dialog.mdx` | yes | 21 |  |  |  |  |
+| `design-tokens` | `@oxy.so/bloom/design-tokens` + barrel | universal | `design-tokens.mdx` | yes | 6 |  |  |  |  |
+| `dialog` | `@oxy.so/bloom/dialog` + barrel | web fork | `dialog.mdx` | yes | 23 |  |  |  |  |
 | `directions` | `@oxy.so/bloom/directions` + barrel | universal | `directions.mdx` | yes | 3 |  |  |  |  |
 | `divider` | `@oxy.so/bloom/divider` + barrel | universal | `divider.mdx` | yes | 1 |  |  |  |  |
-| `dot-grid-meter` | `@oxy.so/bloom/dot-grid-meter` + barrel | universal | `dot-grid-meter.mdx` | yes | 2 |  |  |  |  |
 | `dropdown-menu` | `@oxy.so/bloom/dropdown-menu` + barrel | web fork | `dropdown-menu.mdx` | yes | 5 |  |  | reads | reads |
 | `earnings` | `@oxy.so/bloom/earnings` + barrel | universal | `earnings.mdx` | yes | 2 |  |  |  | reads |
 | `empty-state` | `@oxy.so/bloom/empty-state` + barrel | universal | `empty-state.mdx` | yes | 1 |  |  |  |  |
 | `error-boundary` | `@oxy.so/bloom/error-boundary` + barrel | universal | `error-boundary.mdx` | yes | 2 |  |  |  |  |
 | `eviction` | `@oxy.so/bloom/eviction` + barrel | universal | `eviction.mdx` | yes | 2 |  |  |  |  |
 | `fab` | `@oxy.so/bloom/fab` + barrel | web fork | `fab.mdx` | yes | 4 |  | reads |  |  |
-| `field` | `@oxy.so/bloom/field` + barrel | universal | `field.mdx` | yes | 13 | reads |  |  |  |
+| `field` | `@oxy.so/bloom/field` + barrel | universal | `field.mdx` | yes | 14 | reads |  |  |  |
 | `file-upload` | `@oxy.so/bloom/file-upload` + barrel | universal | `file-upload.mdx` | yes | 4 | reads |  |  |  |
 | `fill` | `@oxy.so/bloom/fill` + barrel | universal | `fill.mdx` | yes | 1 |  |  |  |  |
 | `floating` | internal | universal | — | — | 18 | n/a¹ |  | reads | reads |
@@ -210,7 +211,7 @@ The classification is an EQUALITY in `src/__tests__/adoption-matrix.test.ts`, no
 | `listing-details` | `@oxy.so/bloom/listing-details` + barrel | universal | `listing-details.mdx` | yes | 5 |  |  |  | reads |
 | `listing-editor` | `@oxy.so/bloom/listing-editor` + barrel | universal | `listing-editor.mdx` | yes | 2 | **adaptation** |  |  | reads |
 | `loading` | `@oxy.so/bloom/loading` + barrel | web fork | `loading.mdx` | yes | 3 |  | reads |  |  |
-| `locale` | `@oxy.so/bloom/locale` + barrel | universal | `locale.mdx` | — | 23 |  |  |  |  |
+| `locale` | `@oxy.so/bloom/locale` + barrel | universal | `locale.mdx` | — | 24 |  |  |  |  |
 | `location-puck` | `@oxy.so/bloom/location-puck` + barrel | universal | `location-puck.mdx` | yes | 2 |  |  |  |  |
 | `lyrics` | `@oxy.so/bloom/lyrics` + barrel | universal | `lyrics.mdx` | yes | 3 |  |  |  |  |
 | `mail-compose` | `@oxy.so/bloom/mail-compose` + barrel | universal | `mail-compose.mdx` | yes | 4 | reads |  |  | reads |
@@ -231,6 +232,7 @@ The classification is an EQUALITY in `src/__tests__/adoption-matrix.test.ts`, no
 | `message-bubble` | `@oxy.so/bloom/message-bubble` + barrel | universal | `message-bubble.mdx` | yes | 2 |  |  |  |  |
 | `message-media` | `@oxy.so/bloom/message-media` + barrel | universal | `message-media.mdx` | yes | 3 | n/a¹ |  |  |  |
 | `motion` | `@oxy.so/bloom/motion` + barrel | web fork | `motion.mdx` | yes | 4 |  |  |  |  |
+| `multi-agent-chat` | `@oxy.so/bloom/multi-agent-chat` + barrel | web fork | `multi-agent-chat.mdx` | yes | 4 |  |  |  |  |
 | `music-library` | `@oxy.so/bloom/music-library` + barrel | universal | `music-library.mdx` | yes | 4 | n/a¹ |  |  |  |
 | `navigation-banner` | `@oxy.so/bloom/navigation-banner` + barrel | universal | `navigation-banner.mdx` | yes | 2 |  |  |  |  |
 | `note-card` | `@oxy.so/bloom/note-card` + barrel | universal | `note-card.mdx` | yes | 2 | n/a¹ |  |  |  |
@@ -241,7 +243,7 @@ The classification is an EQUALITY in `src/__tests__/adoption-matrix.test.ts`, no
 | `order-confirmation` | `@oxy.so/bloom/order-confirmation` + barrel | universal | `order-confirmation.mdx` | yes | 1 |  |  |  |  |
 | `order-status` | `@oxy.so/bloom/order-status` + barrel | universal | `order-status.mdx` | yes | 1 |  |  |  |  |
 | `outline-nav` | `@oxy.so/bloom/outline-nav` + barrel | universal | `outline-nav.mdx` | yes | 2 |  |  |  |  |
-| `overlay` | `@oxy.so/bloom/overlay` + barrel | universal | `overlay.mdx` | yes | 16 |  |  |  |  |
+| `overlay` | `@oxy.so/bloom/overlay` + barrel | universal | `overlay.mdx` | yes | 17 |  |  |  |  |
 | `page-header` | `@oxy.so/bloom/page-header` + barrel | universal | `page-header.mdx` | yes | 5 |  |  |  |  |
 | `pagination` | `@oxy.so/bloom/pagination` + barrel | universal | `pagination.mdx` | yes | 2 |  |  |  |  |
 | `patient-info-card` | `@oxy.so/bloom/patient-info-card` + barrel | universal | `patient-info-card.mdx` | yes | 1 |  |  |  |  |
@@ -258,6 +260,7 @@ The classification is an EQUALITY in `src/__tests__/adoption-matrix.test.ts`, no
 | `pressable-scale` | `@oxy.so/bloom/pressable-scale` + barrel | universal | `pressable-scale.mdx` | yes | 1 |  |  |  |  |
 | `price-breakdown` | `@oxy.so/bloom/price-breakdown` + barrel | universal | `price-breakdown.mdx` | yes | 3 |  |  |  | reads |
 | `progressive-blur` | `@oxy.so/bloom/progressive-blur` + barrel | web fork | `progressive-blur.mdx` | yes | 1 |  |  |  |  |
+| `project-board` | `@oxy.so/bloom/project-board` + barrel | web fork | `project-board.mdx` | yes | 1 |  |  |  |  |
 | `proof-of-delivery` | `@oxy.so/bloom/proof-of-delivery` + barrel | universal | `proof-of-delivery.mdx` | yes | 1 |  |  |  | reads |
 | `property-insights` | `@oxy.so/bloom/property-insights` + barrel | universal | `property-insights.mdx` | yes | 5 |  |  |  | reads |
 | `provider` | `@oxy.so/bloom/provider` | universal | `provider.mdx` | yes | 3 |  |  |  |  |
@@ -278,7 +281,7 @@ The classification is an EQUALITY in `src/__tests__/adoption-matrix.test.ts`, no
 | `settings-modal` | `@oxy.so/bloom/settings-modal` + barrel | universal | `settings-modal.mdx` | yes | 10 |  |  |  | reads |
 | `shapes` | `@oxy.so/bloom/shapes` + barrel | universal | `shapes.mdx` | yes | 4 |  |  |  |  |
 | `shipment-request` | `@oxy.so/bloom/shipment-request` + barrel | universal | `shipment-request.mdx` | yes | 1 | **adaptation** |  |  |  |
-| `sidebar` | `@oxy.so/bloom/sidebar` + barrel | universal | `sidebar.mdx` | yes | 10 | n/a¹ | reads |  | reads |
+| `sidebar` | `@oxy.so/bloom/sidebar` + barrel | universal | `sidebar.mdx` | yes | 11 | n/a¹ | reads |  | reads |
 | `skeleton` | `@oxy.so/bloom/skeleton` + barrel | universal | `skeleton.mdx` | yes | 1 |  |  |  |  |
 | `slider` | `@oxy.so/bloom/slider` + barrel | universal | `slider.mdx` | yes | 5 | reads | reads |  |  |
 | `social-button` | `@oxy.so/bloom/social-button` + barrel | web fork | `social-button.mdx` | yes | 2 |  | reads |  |  |
@@ -289,9 +292,9 @@ The classification is an EQUALITY in `src/__tests__/adoption-matrix.test.ts`, no
 | `stay-search` | `@oxy.so/bloom/stay-search` + barrel | universal | `stay-search.mdx` | yes | 5 |  |  |  |  |
 | `stepper` | `@oxy.so/bloom/stepper` + barrel | universal | `stepper.mdx` | yes | 4 | reads | reads |  |  |
 | `sticker` | `@oxy.so/bloom/sticker` + barrel | web fork | `sticker.mdx` | yes | 1 |  |  |  |  |
-| `styles` | `@oxy.so/bloom/styles` + barrel | universal | `styles.mdx` | yes | 83 | n/a¹ |  |  |  |
+| `styles` | `@oxy.so/bloom/styles` + barrel | universal | `styles.mdx` | yes | 84 | n/a¹ |  |  |  |
 | `subtle-hover` | `@oxy.so/bloom/subtle-hover` + barrel | universal | `subtle-hover.mdx` | yes | 1 |  |  |  |  |
-| `surface` | `@oxy.so/bloom/surface` + barrel | web fork | `surface.mdx` | yes | 37 |  |  |  |  |
+| `surface` | `@oxy.so/bloom/surface` + barrel | web fork | `surface.mdx` | yes | 38 |  |  |  |  |
 | `surfaces` | `@oxy.so/bloom/surfaces` + barrel | web fork | `alert.mdx` | yes | 3 |  |  |  |  |
 | `swipe-row` | `@oxy.so/bloom/swipe-row` + barrel | universal | `swipe-row.mdx` | yes | 2 |  |  |  |  |
 | `switch` | `@oxy.so/bloom/switch` + barrel | universal | `switch.mdx` | yes | 7 | reads | reads |  | reads |
@@ -304,12 +307,12 @@ The classification is an EQUALITY in `src/__tests__/adoption-matrix.test.ts`, no
 | `tenancy` | `@oxy.so/bloom/tenancy` + barrel | universal | `tenancy.mdx` | yes | 5 |  | reads |  |  |
 | `text-field` | `@oxy.so/bloom/text-field` + barrel | universal | `text-field.mdx` | yes | 16 | reads | reads |  |  |
 | `textarea` | `@oxy.so/bloom/textarea` + barrel | universal | `textarea.mdx` | yes | 4 | reads | reads |  | n/a¹ |
-| `theme` | `@oxy.so/bloom/theme` + barrel | web fork | `theme.mdx` | yes | 345 |  |  | n/a¹ | reads |
+| `theme` | `@oxy.so/bloom/theme` + barrel | web fork | `theme.mdx` | yes | 351 |  |  | n/a¹ | reads |
 | `theme-toggle` | `@oxy.so/bloom/theme-toggle` + barrel | universal | `theme-toggle.mdx` | yes | 2 | n/a¹ |  |  |  |
 | `toast` | `@oxy.so/bloom/toast` + barrel | universal | `toast.mdx` | yes | 17 |  |  |  |  |
 | `tooltip` | `@oxy.so/bloom/tooltip` + barrel | web fork | `tooltip.mdx` | yes | 1 |  |  |  |  |
 | `track-list` | `@oxy.so/bloom/track-list` + barrel | universal | `track-list.mdx` | yes | 3 |  |  |  | **adaptation** |
-| `typography` | `@oxy.so/bloom/typography` + barrel | universal | `typography.mdx` | yes | 8 |  |  |  |  |
+| `typography` | `@oxy.so/bloom/typography` + barrel | universal | `typography.mdx` | yes | 9 |  |  |  |  |
 | `user-hover-card` | `@oxy.so/bloom/user-hover-card` + barrel | universal | `user-hover-card.mdx` | yes | 4 |  |  |  |  |
 | `vehicle-picker` | `@oxy.so/bloom/vehicle-picker` + barrel | universal | `vehicle-picker.mdx` | yes | 2 | **adaptation** |  |  |  |
 | `vendor-card` | `@oxy.so/bloom/vendor-card` + barrel | universal | `vendor-card.mdx` | yes | 2 |  |  |  |  |

package/docs/agent-avatar.mdx

@@ -0,0 +1,24 @@
+---
+title: Agent Avatar
+description: Procedural agent artwork with editable recipes, expressions and motion.
+---
+
+# Agent Avatar
+
+`AgentAvatar` draws the same artwork with `react-native-svg` on web, iOS and Android. Recipes retain their own colors when the application theme changes.
+
+```tsx
+import { AgentAvatar, FOLD_CONFIG } from '@oxy.so/bloom/agent-avatar';
+
+<AgentAvatar config={{ ...FOLD_CONFIG, eyes: 'curious', hue: 254 }} size={64} label="Peri" />
+```
+
+`config` is an `AvatarConfig`. The published presets include blobs, folded paper and aliens; the original recipe schema also retains its mascot settings. The source artwork currently renders the mascot family through the blob silhouette and material path; outfit and activity settings have no additional renderer. `parsePreset` validates saved recipes and migrates older field values.
+
+Change `entranceKey` to replay the curled arrival and `workingKey` to play a hop and full paper turn. `workingCycles` defaults to one. `paused`, reduced motion and `motion: 0` freeze animation; expression and explicit gaze changes still render. Sleeping agents use closed lids and four drifting sleep marks. The original `interactive` and `portrait` compatibility props remain reserved.
+
+`className` and `style` apply to the outer layout node through Bloom's NativeWind wrapper. `label` defaults to the translated “Agent avatar” in the nearest locale scope (`locale` overrides it); `accessibilityLabel` overrides it. Prefer a meaningful name when the image identifies an agent.
+
+The renderer preserves the original silhouettes, projection, expression springs, blink timing, attention, wandering, fold turns, shape morphs, gradient stops and deterministic grain tile. It updates drawing geometry on the JavaScript animation clock and pauses in the background or when outside the viewport on web. Large animated grids should be profiled on the target device.
+
+Grain uses the original seed-713 tile and `soft-light` compositing on isolated React Native view layers, shared with web. This requires the new native renderer and Android 10 or later; older native renderers do not implement this blend mode. Blob grain follows the original backing-pixel scale (capped at 2×), while paper grain follows the original CSS-pixel scale. Sleep marks retain the original `ui-rounded, system-ui, sans-serif` font stack; installed fonts can differ between platforms. Physical-device pixel comparisons remain necessary.

package/docs/agent-creator.mdx

@@ -0,0 +1,50 @@
+---
+title: AgentCreator
+description: Controlled agent profile editor with live avatar, emotion orbit, shape arc, custom color, and speech preferences.
+order: 105
+---
+
+# AgentCreator
+
+A controlled editor for an agent's name, label, description, appearance and response preferences. The host owns the agent, saving, and the surrounding panel. The implementation is shared across web, iOS and Android; the platform entry points bind Bloom's existing select and popover surfaces.
+
+```tsx
+import { useState } from 'react';
+import { AgentCreator, type AgentCreatorAgent } from '@oxy.so/bloom/agent-creator';
+import { FOLD_CONFIG } from '@oxy.so/bloom/agent-avatar';
+
+const [agent, setAgent] = useState<AgentCreatorAgent>({
+  id: 'designer', name: 'Designer', label: 'Design', description: '',
+  avatar: { ...FOLD_CONFIG },
+});
+
+<AgentCreator agent={agent} onChange={setAgent} onClose={closePanel} />;
+```
+
+Mount under `BloomProvider` and give the editor a bounded height. Layout classes resolve through Bloom's styled primitives; web consumers must scan Bloom's built `lib/` in their NativeWind/Tailwind pipeline.
+
+## Appearance
+
+The preview is 162px. Sixteen upright expression chips orbit at a 116px radius; dragging or a mouse wheel rotates the orbit. Hover, focus, backgrounding and reduced motion pause automatic movement. The shape selector uses the source's 210px circular track, unbounded index, spring, drag and wheel geometry. Choose a silhouette by pressing it; keyboard arrows, Home and End select shapes on web. BloomProvider’s direction reverses horizontal movement in RTL.
+
+Nine glossy color presets preserve the avatar's other controls. The custom picker contains a saturation/brightness field, hue rail and hex entry; dark custom fills switch to light eyes. HSV state preserves the selected hue when the field reaches black or gray. Invalid hex input resets to the last emitted color. Speech and appearance edits preserve the agent's identity and unrelated fields.
+
+## Preferences and speech
+
+`AgentPreferences` carries `voice`, `speed`, `language` and `notifications`. Defaults are voice `alice`, speed `1`, language `auto`, notifications `true`. Supported speeds are `0.75`, `1`, `1.25`, `1.5`; languages are auto-detect, English, Turkish, Spanish, French, German, Japanese and Portuguese. `normalizeAgentPreferences()` restores supported values and limits voice identifiers to 200 characters.
+
+Web previews use the browser's local device voice catalog and cancel playback when the editor unmounts. iOS and Android hosts provide `voices` (`{ id, name, language }[]`) and `onPreviewVoice(text, preferences)` to integrate their own speech provider; no speech dependency is added to Bloom. Without a provider, native speech selection and preview are disabled while saved preferences remain intact. Changing notification preferences updates data; delivering a notification belongs to the consumer.
+
+`className` and `style` apply to the editor's outer node. Profile limits are 48 characters for name, 60 for label and 500 for description. `onClose` closes the host panel and does not save.
+
+## Locale and shared primitives
+
+All fixed labels, hints, accessible names and picker values use the `AGENT_CREATOR_MESSAGES` catalog and Bloom’s 15 supported locales. `locale` overrides the root locale for this editor; `labels` overrides individual catalog entries. Agent names, descriptions and host voice names remain consumer data.
+
+Profile inputs, textarea, select, switch, segmented control, close control and popover reuse Bloom’s current primitives. Original layout and interaction class chains are retained. Bloom’s active palette and materials supply their colors. The custom HSV picker reads `Field` membership: disabling the enclosing field disables its gestures, keyboard updates and hex input; field errors and descriptions associate with its inputs.
+
+The original rainbow artwork and glossy color artwork are retained. Web applies the original shape mask and scroll blur; native uses SVG clipping and edge gradients for CSS effects its renderer cannot express. Native gesture hit areas remain rectangular, and native scroll fades do not apply a backdrop blur. These adaptations need device verification.
+
+## Validation boundary
+
+Tests verify profile and avatar edits preserve unrelated data, preference updates, host speech preview, color round trips and shape geometry. Jest does not execute gesture arbitration or the Reanimated frame loop; motion, wheel hit testing, custom picker dragging, and native speech providers require browser/device verification.

package/docs/button.mdx

@@ -28,7 +28,7 @@ An `icon` without children makes a square action. Labelled actions use `leadingI
 
 The pressable is the parent's layout child: `className` and `style` are applied there, without an extra wrapper. Web styles flatten RN style arrays and register their interaction CSS using constructed stylesheets. `asChild` composes an existing web link; disabled state guards the composed handler.
 
-`CloseButton` remains a semantic dismiss control with a required accessible name and sizes `xs | sm | md | lg`.
+`CloseButton` remains a semantic dismiss control with a required accessible name and sizes `xs | sm | md | lg`. Its optional `className` lands on the dismiss pressable, so positioning utilities work on both platforms.
 
 See [Component contract](./appearance.mdx) for inheritance and [Migration](./coherent-system-migration.mdx) for the clean API cut.
 

package/docs/design-tokens.mdx

@@ -291,6 +291,14 @@ and muted/accent aliases do not represent separate elevations.
 - **Shadow**: `shadow-s`, `shadow-m` (web box-shadow). On native surfaces apply
   `bloomShadowStyle('s' | 'm')` (returns RN elevation/shadow props).
 
+Numeric Tailwind utilities retain their authored pixel geometry too: the theme
+uses a 4px `--spacing` unit, pixel-valued radius names (`rounded-3xl` is 24px),
+and pixel-valued container widths. The NativeWind 5 preview otherwise treats
+rem as 14px, shrinking `gap-2.5` to 8.75px. Its Metro option is not forwarded on
+one export path, and a CSS root font size does not fix rem inside inlined custom
+properties. `native-utility-geometry.test.ts` runs Tailwind → native compilation
+without a consumer override and asserts the actual output values.
+
 ### Chart series
 
 `--chart-1` through `--chart-9` and their `--chart-N-active` partners are

package/docs/dialog.mdx

@@ -319,3 +319,9 @@ Dialog panels publish level 0 with the painted tint composited against the page
 ### Shared surface paint
 
 The painted host delegates its fill to Surface: a 90%-opacity body with a subtle refracted edge on web, plus the shared sheen and rim. The host itself stays transparent to avoid painting twice. Explicit alpha colours retain their alpha; descendants receive the corresponding composited fill. Plain or unframed content keeps its existing layout behavior.
+
+### Custom presentation motion
+
+`presentation="custom"` on a centered card lets its content own panel paint and entry/exit motion. Its backdrop is transparent; Bloom retains the portal, overlay ordering, inertness, keyboard/focus behavior, screen scope and imperative close lifecycle. Set `exitDuration` in milliseconds to retain content through its exit. `useDialogContext().isClosing` becomes true when any dismissal starts, including Escape and the backdrop. The default presentation and its material/timings are unchanged. Bottom placement retains the BottomSheet presentation.
+
+Project Board composes its original 480ms create Genie and 560ms detail exit lifetime through this opt-in. On native, this custom centered presentation uses the existing side-sheet overlay infrastructure while its content supplies the panel layout.

package/docs/migrating-to-1.0.mdx

@@ -330,9 +330,9 @@ These break nothing at compile time and change what you see.
 - **Popover positions through the shared placement engine.** Its own resolver
   clamped only the top, so a panel that fit neither above nor below its trigger
   ran off the bottom of the viewport.
-- **`Switch`, `Slider` and `DotGridMeter` warn once, in dev only, when they
-  mount with no accessible name.** All three draw no text, so nothing in the
-  component can supply one. `Switch` and `DotGridMeter` gained an optional
+- **`Switch` and `Slider` warn once, in dev only, when they
+  mount with no accessible name.** Both draw no text, so nothing in the
+  component can supply one. `Switch` gained an optional
   `accessibilityLabel` prop for it; the warning never fires in production, and
   an empty or whitespace-only name counts as missing, because `aria-label=""`
   names nothing.

package/docs/multi-agent-chat.mdx

@@ -0,0 +1,69 @@
+# Multi-agent Chat
+
+`MultiAgentChat` combines individual and group conversations, the agent creator,
+animated avatars, an editable agent library and a demo marketplace.
+
+```tsx
+import { MultiAgentChat } from '@oxy.so/bloom/multi-agent-chat';
+
+<MultiAgentChat
+  onRespond={async (agent, messages, signal) => {
+    const response = await fetch('/api/agents/respond', {
+      method: 'POST', signal,
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ agent, messages }),
+    });
+    if (!response.ok) throw new Error('Agent response failed');
+    return (await response.json()).text;
+  }}
+/>
+```
+
+Without `onRespond`, the workspace returns sample responses. Each participant
+responds in conversation order. Stop cancels the request and reveal timers;
+partial replies remain visible. Chat switching keeps each draft and generation
+separate; deleting a conversation aborts its outstanding work.
+
+`initialWorkspace` supplies agents and conversations; `onWorkspaceChange` exposes
+edits for host persistence. `storageKey` defaults to `bloom:multi-agent-chat` on
+web; set it to `null` to disable browser storage. Native keeps session state until
+the host stores the workspace. Invalid stored data falls back to the initial demo.
+
+`defaultEditorId` initially opens an agent's editor on desktop. The compact editor
+uses a side surface. `voices` and `onPreviewVoice` connect a native speech provider;
+web can use device speech. `onCopy` supplies native clipboard integration; the
+default native fallback opens the share sheet.
+
+Marketplace plugin choices are workspace demo configuration. They do not authorize
+or connect external accounts. Supply real integrations through the host.
+
+The React Native layout and state are shared across platforms. Thin bindings pick
+Bloom's existing web/native Dialog, ComposerPanel and AgentCreator implementations.
+Layout utilities require the consumer NativeWind/Tailwind source scanning described
+in `docs/styles.mdx`. Theme colours come from Bloom's provider.
+
+Group creation and the first group message move the avatar artwork between
+measured positions with the source timings. Web renders the decorative journey
+through a portal; native uses a local absolute overlay that does not intercept
+touches. The preview publishes its exact committed drawing command stream to an internal
+observer. The journey retains that frame and renders it through the same shared
+SVG renderer, preserving the departing face and pose without restarting motion.
+Reduced motion skips the flights and snaps the editor rail into place. Missing
+or unmounted measurements cancel the decoration without delaying responses.
+Reply actions appear on mouse hover or keyboard focus and remain visible on touch.
+
+`providers` replaces the demo model catalogue in the shared `ComposerPanel`.
+Its model picker, stop action, permission picker and attachments retain the
+composer family’s current behavior. The workspace uses the active Bloom locale;
+its application copy is registered with the shared message catalogue.
+
+Marketplace links use the `marketplace` URL parameter on web. A recognized item
+opens directly in its detail view. Notifications render in the shared portal and
+overlay layer without moving the conversation or composer.
+
+The generated Bloom theme fixes numeric spacing to a 4px grid and emits radii
+and container widths in pixels. This preserves the same utility classes and
+geometry on web and native. NativeWind’s default 14px rem otherwise compiles
+`gap-2.5` to 8.75px rather than 10px; the installed preview also drops Metro’s
+`inlineRem` option on one export path. No consumer rem workaround is required
+for these component utilities: import Bloom’s generated theme/preset.

package/docs/project-board.mdx

@@ -0,0 +1,35 @@
+# Project Board
+
+A shared project board for web, iOS and Android. It keeps the original five-column ticket layout, compact member avatars, priority/project chips, sort/filter/display menus, empty-column illustration, create-more flow and ticket detail panel.
+
+```tsx
+import { ProjectBoard } from '@oxy.so/bloom/project-board';
+
+<ProjectBoard
+  initialColumns={columns}
+  members={members}
+  projects={['Bloom', 'Product']}
+  currentUserId="maya"
+  onColumnsChange={saveColumns}
+/>
+```
+
+`initialColumns` is copied on mount. Updates are local until `onColumnsChange` persists them. Limits are display metadata, as in the original board; reaching a limit does not reject a ticket. The package has no demo people or fake activity. The Project Board template outside `src/` supplies the original columns, people, descriptions, discussion, resources and token series.
+
+Tickets carry description, assignees, priority, project, favorite state and comments. `resources` supplies external resource chips; `tokenUsage` supplies the existing `TokensChartCard`. Opening a card calls `onTicketOpen`. `initialTicketId` opens a detail panel on mount; web also recognizes `#ticket=<id>` and hash changes. Provide `onCopyTicketLink` and `onCopyTicketId` for the product's native clipboard and routing integration; web defaults to the current URL and browser clipboard. Copy failures are announced.
+
+Creation and detail panels use `useDialogControl()` through Bloom's platform-bound Dialog. Creation trims fields, rejects a blank title and supports creating several tickets without closing. Detail edits persist immediately; description editing has Save/Cancel. Comments reject whitespace and append without replacing history.
+
+Drag uses Gesture Handler and Reanimated on both platforms: mouse movement activates after five pixels; touch activates after 180 ms. Hit testing chooses the column underneath the pointer before its ticket positions, so a short neighboring column cannot steal a drop. Empty columns accept drops; dropping outside or cancelling leaves the original order intact. Filtered moves preserve hidden tickets. Drag sets sorting back to manual. Pointer proximity scrolls columns and the board during movement.
+
+On web, Enter opens a ticket; space picks it up, arrows move it, space commits and Escape restores the previous order. Left/right follow the locale direction. Native screen-reader actions move up/down or to an adjacent column. Fixed strings use the Project Board catalog in all fifteen Bloom languages. Direction follows the existing locale/I18nManager hook; content supplied in props remains product data.
+
+## Motion and verification
+
+The original Tailwind class recipes, custom SVG glyphs, empty-state geometry and reveal timing remain in the shared NativeWind content. The template preserves the original 272px drawer, 325ms reveal, 273px columns and shell insets while reusing Bloom’s current Sidebar. Buttons, chips, fields, selectors, menus, tooltips and charts compose Bloom 6.4 primitives. Palette and material follow the current Bloom theme.
+
+Web runs the original create Genie displacement field and the detail Genie’s cached perspective bands: live content remains interactive at rest; visual copies are inert and have rebased SVG IDs. The dialogs retain Bloom’s imperative lifecycle, focus handling and overlay stack through `presentation="custom"`. Entry/exit reverse from the current shape when interrupted and respect reduced motion.
+
+React Native can animate the original stretch, scale, translation and timing through Reanimated, but it does not expose a View’s live pixels as `feDisplacementMap` input or DOM clipping bands. Those two pixel deformations remain specific to web. Native touch/paint behavior has not been verified on a physical device; platform CSS exports do not establish pixel equivalence.
+
+Chrome at 1440×900 compared the original and Bloom side by side: create measured 560×230px and detail 609×876px in both, with the original descriptions, people, resources, activity and token data. Real browser checks cover wide/compact, dark and RTL rendering, keyboard moves, creation, favorites, comments and Escape. Thirteen focused Jest cases cover data transitions, interactions and default/custom Dialog completion semantics. Browser keyboard capture is intentional because react-native-web consumes space before bubbling. Pointer dragging remains a separate browser check; the final scripted drag started from a card outside the horizontally scrolled viewport and did not establish a drop result.

package/docs/segmented-control.mdx

@@ -130,3 +130,5 @@ the application root, as for BottomBar. The plain variant also accepts dragging.
 ## API migration
 
 Controls use canonical sizes and the shared visual scope. Removed aliases and migration mappings are documented in [Unified component API](/docs/unified-api).
+
+`className` is supported by the root and each `SegmentedControlItem`. An item’s layout, press behavior and measured indicator geometry share one pressable node; `flex-1` therefore lays out the selectable item on both platforms.

package/docs/settings-modal.mdx

@@ -79,6 +79,8 @@ In `compact`, `SettingsRow` lets its control wrap under the label when both do n
 
 Every layout uses `PageHeader` with its floating islands. A `ButtonGroupItem` supplies the close action; compact pages use its native back action to return to sections. The modal owns safe-area padding once, so the header uses `safeArea={false}`. The page viewport fills the entire content panel: its first child is the sticky header, followed by the padded page body. Native uses `stickyHeaderIndices`; web uses the header’s CSS sticky positioning. The viewport’s own Reanimated scroll offset drives `PageHeader`’s automatic scrim in the modal surface color, independently of the document beneath it. There is no second body viewport or separate fade. Compact section navigation uses the same structure in its rail viewport. Changing pages remounts the page viewport and resets its scroll offset. `PageHeader` owns header metrics; only the page body owns content padding.
 
+Pages with `fullBleed: true` own their scrolling and insets. A `content` render callback receives `{ onBack, backLabel, onClose, closeLabel }` and owns its header too: `onBack` returns to sections on compact screens and is absent beside the desktop rail. Render that action in the page’s existing header to avoid a second title. A full-bleed page with static React content keeps the compact shell’s back header. The default page layout continues to use its shared `PageHeader`.
+
 ## Why it is not a `Dialog`
 
 This shell differs from `Dialog`'s centered card in every load-bearing way: black 70% backdrop with no blur, 24px radius on `background/full`, a fixed 871×614 size, a fade + scale-from-0.85 + 4px blur on `cubic-bezier(0.32, 0.72, 0, 1)`, and a **Saved toast that straddles the panel's bottom edge** — outside the panel's clip, which `Dialog`'s card owns. So the shell is built from the same authorities `Dialog` uses — `Portal`, `OverlayRoot` (the one stacking rank) and `Backdrop` (the pointer-events contract) — and accepts `Dialog`'s `control`.

package/docs/sidebar.mdx

@@ -283,6 +283,14 @@ which also moves its footer. The default `start` preserves existing placement.
 
 Card and docked sidebar surfaces paint the shared Surface material at 90% body opacity with its gradient and rim beneath their contents; plain surfaces and the navigation rail retain their existing fill. The current logo, modes, scoped sizes, tree, custom content, RTL layout, safe edges and scroll behavior are unchanged. Storybook: **Blocks / Sidebar / Glass Panel**.
 
+`header` replaces the account/logo header while keeping it outside the existing destination scroll. A render function receives `{ collapsed }`. `contentPadding` changes the expanded inset and the measured width of app-owned content together; omit it to preserve the size's default inset. `className` reaches the panel's animated layout node. Navigation rows also accept `style` and `className`; collapsed rows retain the sidebar's square geometry.
+
+`SidebarToolbar` composes action slots beside controlled `search` (`value`, `onValueChange`, `open`, `onOpenChange`, optional names and placeholder). Opening search expands it across those slots, focuses its input and removes hidden actions from interaction, accessibility and web tab order. Close and Escape clear the query and restore the search trigger. The 300ms width and 200ms action fade/transform respect reduced motion. Buttons and fields reuse Bloom's existing bases.
+
+`SidebarItem` accepts `leading` in place of an icon, a secondary `description`, and `selectedAppearance="neutral"` for a tertiary surface instead of the default accent selection. Descriptive rows constrain both text lines for ellipsis and collapse them together. `labelClassName` and `descriptionClassName` reach the text nodes; existing icon-only rows and default selection retain their previous recipe. Press events, native holds, trigger ARIA props and refs reach the host for `asChild` menu composition.
+
+Multi Agent Chat uses these pieces with one sidebar scroll owner. Chrome measured its panel at 260×876px, toolbar at 244×36px, conversation rows at 244×54px and footer actions at 36px. Real pointer checks cover search filtering, close, right-click actions and renaming. Native context-menu hold composition is covered by Jest; device rendering and motion remain separate verification.
+
 ### Shared surface paint
 
 The painted host delegates its fill to Surface: a 90%-opacity body with a subtle refracted edge on web, plus the shared sheen and rim. The host itself stays transparent to avoid painting twice. Explicit alpha colours retain their alpha; descendants receive the corresponding composited fill. Plain or unframed content keeps its existing layout behavior.

package/docs/stat-widgets.mdx

@@ -1,12 +1,12 @@
 ---
 title: Choosing a stat widget
-description: Four families, four different questions about a number.
+description: Three families, three different questions about a number.
 order: 61
 ---
 
 # Choosing a stat widget
 
-Bloom has four small data-display families. They are separate because each
+Bloom has three small data-display families. They are separate because each
 answers a different question, and picking the wrong one makes a number harder
 to read rather than easier.
 
@@ -14,10 +14,9 @@ to read rather than easier.
 | ----------------------------------------------------- | ---------------------------------------- |
 | [`CompositionBar`](/docs/bloom/main/composition-bar)  | what is this total **made of**?           |
 | [`StatBar`](/docs/bloom/main/stat-bar)                | how far along, or how is it split in two? |
-| [`DotGridMeter`](/docs/bloom/main/dot-grid-meter)     | how many out of a countable total?        |
 | [`ActivityHeatmap`](/docs/bloom/main/activity-heatmap) | when did this happen, over time?          |
 
-Two rules apply to all four.
+Two rules apply to all three.
 
 ## Colours are the app's, not the theme's