@oxyhq/bloom 0.89.0 → 1.0.1

package/docs/migrating-to-1.0.mdx

@@ -0,0 +1,434 @@
+---
+title: Migrating to 1.0
+description: Bloom 1.0.0 moves with @oxyhq/services 30.0.1 and @oxyhq/core 21.0.0 as one upgrade, plus every breaking change between 0.89.0 and 1.0.0, derived from the published tarballs rather than from commit messages.
+order: 2
+---
+
+# Migrating to 1.0
+
+Bloom follows the clean-cut rule: there are no `@deprecated` aliases and no
+old-name shims anywhere in this release. **This page is the only bridge.** If a
+name below is gone, it is gone in the build you install — nothing re-exports it
+under the old spelling.
+
+<Callout variant="info" title="Which version are you on?">
+`0.87.1 → 0.88.0 → 0.89.0` was **purely additive**: seven new symbols on
+`@oxyhq/bloom/design-tokens` plus the `./design-tokens/tokens.json` subpath, and
+nothing removed or renamed. So every change on this page applies in full whether
+you are coming from 0.87.1, 0.88.0 or 0.89.0.
+</Callout>
+
+<Callout variant="warning" title="`^` means something different now">
+Under a `0.x` version, `^0.89.0` resolves to `>=0.89.0 <0.90.0` — a caret pinned
+you to one minor. From 1.0.0, `^1.0.0` resolves to `>=1.0.0 <2.0.0`, so a caret
+now accepts every future minor. That is the intended semantics, but it is a
+change in what your existing range does.
+</Callout>
+
+## Before anything else: this is a three-package upgrade
+
+Bloom 1.0.0 is not a package you can bump on its own. If your app also uses
+`@oxyhq/services`, the move is **three packages in one commit**:
+
+```json
+"@oxyhq/bloom": "^1.0.0",
+"@oxyhq/services": "^30.0.1",
+"@oxyhq/core": "^21.0.0"
+```
+
+Not three steps. Both intermediate states are broken, and neither announces
+itself: one cannot produce a warning at all, and the other produces exactly one
+line, on one run.
+
+### Bloom alone breaks `@oxyhq/services`, silently
+
+Every published `@oxyhq/services` below `30.0.0` imports two subpaths that 1.0.0
+deleted, from its own source:
+
+| File in `@oxyhq/services` | Imports |
+| --- | --- |
+| `src/ui/components/FollowTargetButton.tsx` | `@oxyhq/bloom/menu` |
+| `src/ui/components/authChooser/TroubleDisclosure.tsx` | `@oxyhq/bloom/collapsible` |
+
+Both are present in the published `29.0.0` tarball in `src/` **and** in both
+compiled `lib/` trees, so it does not matter whether your bundler reads Bloom's
+source or its build. Neither is in `30.0.1`. `FollowTargetButton` is the one that
+usually surfaces first, because it is on the follow button most apps render.
+
+Nothing warns you, and it is not that the warning is easy to miss — **no warning
+is possible.** Every `@oxyhq/services` below 30 declares its Bloom peer as
+`">=0.59.0"` (or looser), an unbounded range that `1.0.0` satisfies. There is no
+mismatch for a package manager to report. `@oxyhq/bloom` declares no `@oxyhq/*`
+peer of its own, so it cannot report one either. The failure appears at bundle
+time as an unresolved module — on web, typically a white screen.
+
+### `@oxyhq/services` alone breaks against an old `@oxyhq/core`
+
+`@oxyhq/services@30.0.1` names **12 `@oxyhq/core` symbols across 10 of its own
+source files that do not exist in `@oxyhq/core@20.1.0`**: `DeviceContext`,
+`SharedDeviceCredential`, `SharedDeviceCredentialRead`,
+`SharedDeviceCredentialStore`, `SwitcherContextRow`, `SwitcherPrincipalRow`,
+`buildSwitcherRows`, `createSharedMirroringAuthStateStore`,
+`normalizeSharedDeviceSessionRead`, `projectDevicePrincipals`,
+`resolveActiveContext` and `showsPrincipalHeaders`. All 144 core bindings
+services imports exist in `21.0.0`.
+
+This is not new in 30 — `@oxyhq/services@29.0.0` names the same 12. The core
+floor moved to `^21.0.0` in services 29, so if you are skipping several majors
+you are crossing it whichever version you land on.
+
+Here the package manager does speak, but only just:
+
+```
+warn: incorrect peer dependency "@oxyhq/core@20.1.0"
+```
+
+One line, naming the version but not which package wanted what, on the run that
+actually resolves. Re-run `bun install` against a lockfile that already
+satisfies the tree and you get `Checked N installs ... (no changes)` and no
+warning at all — which is the state most people are in by the time they look.
+
+<Callout variant="warning" title="Do not install `@oxyhq/services@30.0.0`">
+It is deprecated on npm: it published without `lib/`, so 26 of its 33 exports
+targets are missing. `30.0.1` is the version.
+</Callout>
+
+### Whether your typecheck can see any of this
+
+`@oxyhq/services` publishes its main entry with a `react-native` condition that
+is a **bare string** pointing at TypeScript source:
+
+```json
+"exports": { ".": { "react-native": "./src/index.ts", "import": { … }, … } }
+```
+
+So a project whose `customConditions` include `react-native` resolves
+`@oxyhq/services` to `node_modules/@oxyhq/services/src/index.ts` and typechecks
+the package's own source — the core mismatch lands as errors under
+`node_modules/`, all naming `"@oxyhq/core"` (19 of them for `30.0.1` against
+core `20.1.0`). A project without that condition resolves to
+`lib/typescript/module/index.d.ts` instead, and with `skipLibCheck: true` — the
+default in the Expo and Vite templates — **sees nothing at all: zero errors.**
+Its build is green and its web bundle white-screens.
+
+Which side you are on:
+
+```bash
+# from the package directory, not the monorepo root, and name the tsconfig your
+# typecheck script names — a references-only root tsconfig resolves nothing
+bunx tsc -p tsconfig.json --showConfig | grep customConditions
+```
+
+`["react-native"]` means your typecheck is a real check. No output means it is
+not, and a green typecheck is not evidence about this upgrade. Expo apps get the
+condition from `expo/tsconfig.base`; DOM/Vite packages generally do not.
+
+If you are on the blind side and want one run that can see it, typecheck once
+with `--skipLibCheck false`: services' shipped declarations reference the same
+core symbols, so a stale core produces errors there too (fewer of them — 4 in
+the case measured — but enough to fail the run).
+
+### Assert the version that resolved, not the one you declared
+
+Two ways a "done" upgrade is not done:
+
+- **A `packages/*` workspace glob does not match the repo root manifest.** A
+  version pinned in five places, four of them under `packages/`, edits cleanly,
+  and `bun install` answers `Checked 1539 installs (no changes)` — the root
+  manifest still pins the old major and `node_modules` never moved.
+- **A caret range that a lockfile already satisfies does not re-resolve.**
+
+Both are invisible if you read `package.json`. Read what resolved instead, from
+each workspace package:
+
+```bash
+bun pm ls | grep -E '@oxyhq/(bloom|services|core)@'
+# or, from the package directory:
+node -e 'for (const p of ["@oxyhq/bloom","@oxyhq/services","@oxyhq/core"]) console.log(p, require(p + "/package.json").version)'
+```
+
+Expect `1.0.0`, `30.0.1` and `21.0.0`. Anything else means the edit did not land.
+
+<Callout variant="info" title="How the numbers on this page were measured">
+Everything above was read out of the published npm tarballs and registry
+metadata for `@oxyhq/bloom@1.0.0`, `@oxyhq/services@29.0.0` and `30.0.1`, and
+`@oxyhq/core@20.1.0` and `21.0.0`, on 2026-08-17. The symbol counts come from
+an AST walk of services' `src/` cross-checked against each core version's
+exported symbol set through the TypeScript checker; the error counts and the
+warning text come from installing that pair into a scratch project and running
+`tsc` and `bun install` against it. Version numbers move — re-read yours with
+the commands above rather than trusting these.
+</Callout>
+
+## How this list was derived
+
+Not from commit subjects. The published `@oxyhq/bloom@0.87.1` and `0.89.0`
+tarballs were unpacked and their `package.json#exports` compared against this
+build's, and the exported symbol set of each of the 88 typed subpaths was read
+out of `lib/typescript/` on both sides through the TypeScript checker, so a
+re-export barrel is followed rather than guessed. Prop shapes were diffed the
+same way, because a removed prop leaves `ButtonProps` present and its shape
+changed.
+
+One correction that matters if you re-run such a census yourself: a symbol moved
+**into a namespace** looks exactly like a deleted symbol when you only read
+top-level module exports. The fifteen colour-engine names below are in that
+class — they are renamed, not removed.
+
+## Subpaths removed
+
+Four subpaths no longer exist. An import of any of them is a hard resolution
+failure, not a type error.
+
+| Removed | Replacement | Why |
+| --- | --- | --- |
+| `@oxyhq/bloom/menu` | `@oxyhq/bloom/dropdown-menu` | The family was ported to shadcn/react-native-reusables' public API. Every `Menu*` export is `DropdownMenu*`. |
+| `@oxyhq/bloom/collapsible` | `@oxyhq/bloom/accordion` | `Collapsible` called `UIManager.setLayoutAnimationEnabledExperimental(true)` at module scope and reached the root barrel through `export *`, so that side effect ran for every barrel consumer on Android old-arch whether or not the component was used. |
+| `@oxyhq/bloom/grouped-buttons` | `@oxyhq/bloom/settings-list` + `@oxyhq/bloom/item` | The only one of the three row renderers with no `accessibilityRole`, no `accessibilityLabel` and no `aria-disabled`, built on `TouchableOpacity`/`activeOpacity` instead of `useInteractionState`. |
+| `@oxyhq/bloom/pressable-with-hover` | none — inline it | One internal user. It now lives inside `zoomable-image-gallery` as `NavArrow`, the package's only hover-styled control. |
+
+### Subpaths added
+
+`@oxyhq/bloom/dropdown-menu`, `@oxyhq/bloom/menubar`, `@oxyhq/bloom/radio`,
+`@oxyhq/bloom/aspect-ratio`, and the `@oxyhq/bloom/design-tokens/tokens.json`
+asset (the last already shipped in 0.89.0).
+
+## Renamed symbols
+
+Mechanical renames — same component, new name.
+
+| Old | New | Subpath |
+| --- | --- | --- |
+| `Menu`, `MenuTrigger`, `MenuContent`, `MenuItem`, `MenuGroup` | `DropdownMenu`, `DropdownMenuTrigger`, `DropdownMenuContent`, `DropdownMenuItem`, `DropdownMenuGroup` | `./dropdown-menu` |
+| `MenuDivider`, `ContextMenuDivider` | `DropdownMenuSeparator`, `ContextMenuSeparator` | `./dropdown-menu`, `./context-menu` |
+| `useMenuControl`, `useMenuContext`, `MenuControlProps` | declared by `dropdown-menu` itself, no longer re-exported from `dialog` under an alias | `./dropdown-menu` |
+| `Addon` | `InputGroupAddon` | `./input-group` |
+| `Provider`, `Outlet` | `PortalProvider`, `PortalOutlet` | `./portal` |
+| `Attachment` | `PromptInputAttachment` | `./prompt-input` |
+| `zIndex` | `Z_INDEX` | `./styles` |
+| `ChipVariant`, `BadgeVariant` | `AccentFill` | `./theme` |
+| `ChipColor`, `BadgeColor` | `AccentTone` | `./theme` |
+
+`InputGroup.Addon`, the static alias, is gone too — `InputGroupAddon` is the one
+spelling. No Bloom compound carries a static alias.
+
+For `Chip` and `Badge` the accepted **values** are almost unchanged; only the
+type names moved. `BadgeVariant` was already `'solid' | 'subtle' | 'outlined'`,
+which is exactly `AccentFill`, and `BadgeColor` is exactly `AccentTone`. The one
+value that changed is Chip's `'soft'`, which is now `'subtle'`; `AccentTone` also
+adds `'info'` for Chip, which previously had it on `Badge` only.
+
+### The colour engine is one namespace
+
+Fifteen flat exports of `@oxyhq/bloom/theme` are now members of the `ColorEngine`
+namespace, still published from the same subpath:
+
+```ts
+// before
+import { argbFromHex, generateRoleColors, quantizeImage } from '@oxyhq/bloom/theme';
+
+// after
+import { ColorEngine } from '@oxyhq/bloom/theme';
+ColorEngine.argbFromHex(...);
+```
+
+Affected: `argbFromHex`, `hexFromArgb`, `argbFromRgb`, `redFromArgb`,
+`greenFromArgb`, `blueFromArgb`, `quantizeImage`, `seedsFromImagePixels`,
+`seedHexFromImagePixels`, `generateRoleColors`, and the types `RoleName`,
+`RoleColors`, `GenerateOptions`, `SchemeVariant`, `AccentSources`.
+
+`useTheme`, `BloomThemeProvider` and the tokens stay flat — those are used
+fleet-wide and did not move.
+
+### Theme symbols that moved subpath
+
+`getPresetVars`, `buildSeedScopeVars`, `SeedScopeOptions` and `ExplicitAccents`
+were reachable from two subpaths. They now live only in the react-free barrel a
+build script can import:
+
+```ts
+-import { getPresetVars } from '@oxyhq/bloom/theme';
++import { getPresetVars } from '@oxyhq/bloom/design-tokens';
+```
+
+`getPresetVars` and `ExplicitAccents` are also on `@oxyhq/bloom/preset-vars`.
+
+### `alert()` and `confirm()` moved to the surface stack
+
+`alert()` lived on `./dialog`, `confirm()` on `./alert-dialog`. Both are now on
+`@oxyhq/bloom/surfaces`, along with `AlertButton` and `AlertButtonStyle`.
+
+```ts
+-import { alert } from '@oxyhq/bloom/dialog';
+-import { confirm } from '@oxyhq/bloom/alert-dialog';
++import { alert, confirm } from '@oxyhq/bloom/surfaces';
+```
+
+Their hosts — `BloomDialogProvider` and `AlertDialogHost` — are **deleted**, not
+renamed. Both were module-scope FIFO queues with a host component each; remove
+them from your provider tree and mount the single `<SurfaceHost>` instead. A
+one-at-a-time queue orders by arrival into its own queue, so it could not layer
+over a surface it did not know about. Consequence: **two `alert()` calls in a row
+now stack rather than queue.**
+
+`SurfaceConfirmOptions.message` and `SurfacePromptOptions.message` are now
+`description`, matching `DialogProps`.
+
+## Deleted with no replacement
+
+| Symbol | Was on | Note |
+| --- | --- | --- |
+| `BloomDialogProvider` | `./dialog` | see above |
+| `AlertDialogHost`, `ConfirmOptions` | `./alert-dialog` | see above |
+| `TooltipSheetCompatProvider` | `./tooltip` | `return <>{children}</>` on both platforms, zero importers — an unfinished port, not a redundant shim |
+| `SkeletonLoadingProps` | `./loading` | `Loading variant="skeleton"` drew static Views under the same name as the `skeleton` family, which has a real shimmer loop |
+| `useSharedInputStyles` | `./text-field` | module-private; was never usable |
+| `useIsFullscreen` | `./prompt-input` | zero callers |
+| `DIALOG_SHEET_BACKDROP_TESTID` | `./dialog` | off the public surface |
+| `usePopoverControl`, `usePopoverContext`, `PopoverControlProps`, `PopoverPlacement`, `PopoverTriggerRenderProps`, `PopoverTriggerState` | `./popover` | Popover took the Radix shape (`open`/`defaultOpen`/`onOpenChange`, `asChild`, `side`/`align`/`sideOffset`); the render-prop trigger is gone |
+| `MenuItemText`, `MenuItemIcon`, `ContextMenuItemText`, `ContextMenuItemIcon` | `./menu`, `./context-menu` | The four menu families share one row vocabulary now. A row is `DropdownMenuItem` / `ContextMenuItem` with its label as children; use `DropdownMenuShortcut` for trailing text and `DropdownMenuLabel` for a group heading. There is no `*ItemText` or `*ItemIcon` in 1.0.0. |
+
+## Prop changes
+
+| Component | Change |
+| --- | --- |
+| `Button` | `activeOpacity` removed. Press feedback is the library's decision, not a per-call knob. |
+| `Loading` | `variant` no longer accepts `"skeleton"`. Use the `skeleton` family. |
+| `Chip` | `variant="soft"` → `variant="subtle"`, one spelling matching the token family. `color="info"` now exists (it was on `Badge` only). The `onClose` affordance draws `TimesLarge_Stroke2_Corner0_Rounded`, not the `×` glyph. |
+| `Badge` | A `dot` Badge paints the tone's fill whatever the variant — `dot variant="outlined"` used to be a fully transparent circle. |
+| `Popover` | `PopoverContentProps.offset` and `.placement` removed (use `sideOffset` and `side`/`align`); `PopoverProps.control` removed. |
+| `TextField` | `TextFieldIcon` and `TextFieldSuffix` now **throw** outside a `<TextField>`. `TextFieldInput` and `TextFieldLabel` deliberately still work standalone. |
+
+## Behavioural changes with no API change
+
+These break nothing at compile time and change what you see.
+
+- **`Button` heights are now exactly 32 / 36 / 44** (small / medium / large) on
+  both platforms and in every variant. Hit slop brings the two smaller sizes up
+  to the 44dp touch-target floor.
+- **`Button`'s `primary` and `destructive` fills are a glass material** at fill
+  alpha 0.85. `inverse` stays opaque. Full AA cost table in
+  [Button](/docs/bloom/main/button).
+- **`AspectRatio` rejects a degenerate ratio** — a `ratio` that is zero,
+  negative or non-finite falls back to the default instead of collapsing the
+  box.
+- **`ActivityHeatmap`'s default palette declares only the steps it can paint.**
+  `DEFAULT_ALPHAS` carried five steps but the first could never be reached.
+  Rendered with the default props this is byte-identical to what shipped; if you
+  passed your own `levels` **and** relied on the default alphas, re-check the
+  pairing.
+- **`AvatarGroup` resolves identity as `displayName?.trim() || handle`.** It used
+  `??`, which falls through on null/undefined only, so a whitespace-only
+  `displayName` — which the API does send — beat the handle behind it and showed
+  the default avatar image.
+- **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
+  `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.
+- **The neutral surface ramp was respaced** so adjacent surfaces are actually
+  distinguishable in every preset — M3's 2-tone step measured below the
+  just-noticeable difference here. If you pinned Bloom token values in your own
+  fixtures or screenshots, expect them to move.
+- **`AvatarGroup`'s hover card renders off Metro.** Its web fork named
+  `'../portal'` rather than `'../portal/index.web'`, and export conditions do
+  not apply to relative specifiers, so Vite/webpack/SSR got the native `Portal`
+  — which needs a `PortalOutlet` a web app never mounts — and the card drew
+  nothing.
+- **`PromptInput` and `BloomColorScope`/`BloomSeedScope` now work off Metro.**
+  Both shipped `.web` forks with no `browser` condition, so Vite/webpack/SSR
+  resolved the native build: `onImagePaste` was missing entirely and the colour
+  scopes emitted no CSS custom properties at all.
+
+## Structural changes that are not API changes
+
+Every family is now `index.ts` (a pure barrel) + `<Pascal>.tsx` + `types.ts`,
+hooks are `use-kebab-case.ts`, and prop types live in `types.ts`. **The export
+surface is unchanged by that refactor** — measured symbol-for-symbol across all
+barrels, lost=0 gained=0. You only notice if you deep-import a file path inside
+the package, which is not a supported entry point.
+
+## `jest.mock` call sites
+
+A renamed subpath breaks `jest.mock('@oxyhq/bloom/<sub>')` silently — the string
+is not an import, so no type checker and no import census sees it.
+
+Measured across the Oxy fleet: **131 `jest.mock('@oxyhq/bloom/…')` call sites in
+48 files, referencing 20 distinct subpaths — all 20 still exist in 1.0.0.** No
+mock needs to change. The subpaths mocked are `.`, `./avatar`, `./avatar-group`,
+`./bottom-sheet`, `./button`, `./dialog`, `./hooks`, `./icons`, `./item`,
+`./loading`, `./pressable-scale`, `./search`, `./settings-list`, `./skeleton`,
+`./subtle-hover`, `./switch`, `./tab-bar`, `./text-field`, `./theme`, `./toast`.
+
+If you add a mock for `./menu`, `./collapsible`, `./grouped-buttons` or
+`./pressable-with-hover`, it will now silently mock a module that does not exist.
+
+## Measured impact across the Oxy fleet
+
+<Callout variant="warning" title="This section is a scan of local checkouts, not of what you have installed">
+The counts below come from scanning 15,544 tracked source files in the working
+copies of every repo under `~/Oxy` on one machine. A working copy is whatever
+branch someone left it on, which is not the same as any published version — the
+`OxyHQServices` checkout scanned here sat on a topic branch pinned to
+`@oxyhq/services@26.0.1`, four majors behind the published `30.0.1`, and that
+one stale tree is why an earlier revision of this page named only one of the two
+files services imports from a removed subpath. Treat this as a worked example of
+what an upgrade turns up, not as an inventory of your repo. Scan your own:
+
+```bash
+git grep -nE "@oxyhq/bloom/(menu|collapsible|grouped-buttons|pressable-with-hover)['\"]"
+```
+</Callout>
+
+As scanned, excluding Bloom's own tree: **68 call sites in 51 files across 15
+repos need an edit** — Alia, Astro, CRM, Clarity, CrowdSource, Homiio, Inbox,
+Mention, Mercaria, Moovo, Noted, OxyHQServices, Station, Syra and website. Four
+of the 68 were imports of a deleted subpath and the other 64 were named
+bindings, so 68 is a floor: the scan missed `FollowTargetButton.tsx` below,
+which does not exist on the branch the `OxyHQServices` checkout was parked on.
+
+Imports of a removed subpath fail to resolve. They fall into two groups, and the
+fix is different for each.
+
+**In `@oxyhq/services`' own code — fixed by upgrading, not by editing.** Read
+out of the published `29.0.0` tarball rather than from a checkout, so it holds
+for anyone below 30 regardless of what any working copy says:
+
+| File in `@oxyhq/services` (any version below 30) | Subpath |
+| --- | --- |
+| `src/ui/components/FollowTargetButton.tsx` | `./menu` |
+| `src/ui/components/authChooser/TroubleDisclosure.tsx` | `./collapsible` |
+
+**In app code — you edit these.** Present on `origin/main` of each repo as of
+2026-08-17:
+
+| File | Subpath |
+| --- | --- |
+| `Inbox/packages/frontend/components/settings/sections/AccountSection.tsx` | `./grouped-buttons` |
+| `Homiio/packages/frontend/app/host/calendar.tsx` | `./menu` |
+
+Named bindings that no longer exist, by symbol:
+
+| Symbol | Sites | Fix |
+| --- | --- | --- |
+| `getPresetVars` | 10 | import from `@oxyhq/bloom/design-tokens` |
+| `confirm` (from `./alert-dialog`) | 12 | import from `@oxyhq/bloom/surfaces` |
+| `Provider` / `Outlet` (from `./portal`) | 6 + 6 | `PortalProvider` / `PortalOutlet` |
+| `generateRoleColors` | 6 | `ColorEngine.generateRoleColors` |
+| `BadgeColor` | 5 | `AccentTone` |
+| `alert` (from `./dialog`) | 3 | import from `@oxyhq/bloom/surfaces` |
+| `ChipColor`, `ChipVariant` | 2 + 2 | `AccentTone`, `AccentFill` |
+| `BadgeVariant` | 1 | `AccentFill` |
+| `BloomDialogProvider` | 2 | delete; mount `<SurfaceHost>` |
+| `AlertDialogHost` | 1 | delete; mount `<SurfaceHost>` |
+| `Menu*` + `useMenuControl` (one file, `Syra/packages/frontend/components/MediaCard.tsx`) | 7 | `DropdownMenu*` |
+| `Collapsible` (`Astro/webui/.../collapsible-group.tsx`) | 1 | `Accordion` |
+
+`@oxyhq/bloom/icons` is byte-identical between 0.87.1 and 1.0.0 — a census will
+appear to flag three icon names in Bloom's own
+`src/__tests__/icon-references.test.ts`, but those are that suite's own fixture
+strings, not call sites.

package/docs/motion.mdx

@@ -0,0 +1,83 @@
+---
+title: Motion
+description: Shared durations and easings — and the three web failure modes that make animation code lie.
+order: 57
+---
+
+# Motion
+
+Shared enter/exit presets and a screen transition, so a sheet and a menu on the
+same screen do not open at subtly different speeds.
+
+```tsx
+import {
+  ScaleAndFadeIn,
+  ScaleAndFadeOut,
+  ShrinkAndPop,
+  ScreenTransition,
+} from '@oxyhq/bloom/motion';
+
+<Animated.View entering={ScaleAndFadeIn} exiting={ScaleAndFadeOut}>
+  <Panel />
+</Animated.View>
+```
+
+The value of shared presets is not the numbers — it is that a change to "how
+fast things feel" happens in one place rather than being renegotiated per
+component. It is also where the web rules below are already applied, which is
+the stronger reason to use them rather than hand-writing an enter.
+
+## Three ways animation silently does nothing on web
+
+These are not Bloom quirks; they are how Reanimated behaves in the
+configuration every Oxy web app ships. Each fails with **no console output**.
+
+### An animation started from a mapper never ticks
+
+Returning `withTiming` / `withRepeat` from `useDerivedValue` or
+`useAnimatedStyle` does nothing on web. Drive a shared value **imperatively**;
+`useAnimatedStyle` only ever READS.
+
+```tsx
+// ✅ someone calls this
+progress.value = withTiming(1, { duration: 200 });
+
+const style = useAnimatedStyle(() => ({ opacity: progress.value }), [progress]);
+```
+
+### Without the worklets Babel plugin, mappers re-run on their DEPS ARRAY
+
+Not on auto-tracked reads. Omit an animating shared value from the deps and the
+mapper runs once and freezes at frame 1. **List every shared value the mapper
+reads** — note the `[progress]` above, which is doing real work.
+
+`useAnimatedReaction` does not fix this: key it on a changing prop, not on a
+shared value.
+
+### A custom `Keyframe` as `entering` freezes the element
+
+An animation name absent from Reanimated's built-in map also schedules a
+cleanup that pins the element — `position: absolute` plus a frozen box — at
+`duration × 5`. It is a layout bug with no error, and `exiting` is unaffected,
+so it looks intermittent.
+
+## Bloom's rule: pick the mechanism per DIRECTION
+
+- **`entering`** runs on the real element. It is EITHER a predefined builder
+  (`FadeIn`, `SlideInUp`) OR driven imperatively from a shared value. Never a
+  `Keyframe`, never a custom builder.
+- **`exiting`** runs on a throwaway clone, so a custom `Keyframe` is safe there —
+  and is the only way to express a multi-property, multi-stop shape.
+
+Consequences to accept rather than work around: a predefined builder cannot
+combine fade with scale, so a web enter drops one; and `Keyframe` has no
+`.easing()`, so web keyframes run linear unless a per-stop easing happens to
+resolve to one of Reanimated's built-in names. Add intermediate stops if the
+curve matters.
+
+## Verifying
+
+Jest and `tsc` catch none of these. Verify in a real **foregrounded** tab — a
+hidden tab freezes plain CSS transitions too, which mimics "the class didn't
+apply". Read the class attribute, or set `transitionProperty: 'none'` before
+reading computed styles.

package/docs/overlay.mdx

@@ -0,0 +1,75 @@
+---
+title: Overlay
+description: How a portaled surface takes its place in the stack — and the pointer-events rule that fails totally and silently.
+order: 37
+---
+
+# Overlay
+
+`overlay/` exports `OverlayRoot` and `Backdrop`: the one way a portaled surface
+establishes its interactive root, its position in the stack, and its
+press-to-dismiss dim. Do not hand-roll either.
+
+```tsx
+import { OverlayRoot, Backdrop } from '@oxyhq/bloom/overlay';
+
+{open ? (
+  <Portal>
+    <OverlayRoot>
+      <Backdrop onPress={close} progress={progress} />
+      <Panel />
+    </OverlayRoot>
+  </Portal>
+) : null}
+```
+
+## A surface opened LATER paints above one opened earlier
+
+That is decided once, in `overlay/stack.ts`, and applied by `OverlayRoot`.
+**Never give an overlay surface a `zIndex` of its own.**
+
+A per-component constant answers "which is on top" by what a surface *is*
+rather than by when it was opened, so some pairings end up permanently
+inverted — a menu that can never appear above a dialog, whatever order the user
+opened them in.
+
+To add a surface: render its portal body inside `<OverlayRoot>`, and put that
+`OverlayRoot` **inside the guard that makes the surface appear**. The rank is
+taken on mount, so the depth is right on the first paint. Order the parts
+*within* one surface using `useOverlayLayerContext()`.
+
+Toasts are the one deliberate exception: `ToastHost` mounts for the app's whole
+life, so taking a rank would wedge the counter, and it passes an explicit
+`zIndex` instead.
+
+## The `pointerEvents` rule
+
+`box-none` and `box-only` are React Native-only values and **must be passed as
+a prop, never inside a `style` object**.
+
+```tsx
+<View pointerEvents="box-none" style={styles.root} />          // ✅
+<View style={[styles.root, { pointerEvents: 'box-none' }]} />  // ✗ silently dropped
+```
+
+react-native-web resolves those two values from the prop path only; as a style
+entry they are dropped with no warning. `'auto'` and `'none'` *do* survive as
+styles, which is exactly what makes the mistake easy to make and hard to see.
+
+Why it is catastrophic: the web `Portal` root is `pointer-events: none`, and the
+property **inherits**. A dropped opt-in makes the entire surface click-through —
+backdrops do not dismiss, buttons do not press, clicks land on the app behind.
+Escape still works, so it presents as a dismissal bug rather than as a
+pointer-events bug. Outside a portal the same mistake inverts, and a full-bleed
+band silently eats presses.
+
+Verify dismissal in a real browser. Jest cannot see inheritance through a
+portal, and the markup is valid either way.
+
+## Not everything overlay-shaped is in the stack
+
+The **web** tooltip is not portaled and has no rank; the native one is and does.
+Check for a `Portal` before assuming a surface participates.
+
+On native there is a second mechanism z-index cannot reach: each of these
+surfaces is its own RN `<Modal>` window.

package/docs/popover.mdx

@@ -0,0 +1,73 @@
+---
+title: Popover
+description: Arbitrary content anchored to a trigger — a sheet on native, a panel on web.
+order: 21
+---
+
+# Popover
+
+A small surface of arbitrary content, anchored to what opened it. An anchored panel on web, a bottom sheet on native.
+
+Three parts, shadcn's own: `Popover`, `PopoverTrigger`, `PopoverContent`.
+
+Reach for it when the content is not a list of actions. When it IS a list of actions, reach for [DropdownMenu](/docs/bloom/main/dropdown-menu) — it gives you the rows, the keyboard state and the ARIA roles for free.
+
+## Basic
+
+```tsx
+import { Popover, PopoverContent, PopoverTrigger } from '@oxyhq/bloom/popover';
+import { Button } from '@oxyhq/bloom/button';
+import { P } from '@oxyhq/bloom/typography';
+
+<Popover>
+  <PopoverTrigger asChild label="What is this?">
+    <Button variant="secondary">What is this?</Button>
+  </PopoverTrigger>
+
+  <PopoverContent label="Two-factor authentication">
+    <View style={{ padding: 16, gap: 8 }}>
+      <P>A second step when you sign in, so a leaked password is not enough on its own.</P>
+    </View>
+  </PopoverContent>
+</Popover>
+```
+
+## The panel has no padding of its own
+
+Deliberate, and worth knowing before you wonder where the inset went. A popover's body is as often a list of `Item` rows (the combobox, the dialog header's overflow) as it is prose, and rows have to reach the panel edge to show their full-width highlight. So the panel keeps only the 4px vertical rhythm every anchored Bloom surface has, and a prose popover pads its own body — as the example above does.
+
+## Controlled
+
+```tsx
+const [open, setOpen] = useState(false);
+
+<Popover open={open} onOpenChange={setOpen}>
+```
+
+Uncontrolled by default. `onOpenChange` fires either way. Closing it from inside its own content is a `setOpen(false)`.
+
+## Placement (web)
+
+`PopoverContent` takes `side` (`'top' | 'bottom'`, default `'bottom'`), `align` (`'start' | 'center' | 'end'`, default `'center'`), `sideOffset`, `alignOffset`, `minWidth` and `maxWidth`. The surface flips to the other side when the named one does not fit and clamps into the viewport when neither does.
+
+A popover centres on its trigger by default, where a menu starts at its left edge — that is the one placement default the two families disagree on, and it matches shadcn.
+
+## Shape
+
+shadcn's popover is `w-72 p-4`: a fixed 288px card with a 16px inset, not a shrink-wrap around its content. Bloom applies both, first in the style array, so a body that is a list of rows rather than prose overrides them from `style` — the same thing a shadcn call site says with `className="w-auto p-0"`:
+
+```tsx
+<PopoverContent label="Actions" style={{ width: 'auto', padding: 4 }}>
+  <Item title="Profile" onPress={openProfile} />
+</PopoverContent>
+```
+
+Rows have to reach the panel's edge to draw a full-width highlight, which is why `Combobox` and the dialog header's overflow menu both do this.
+
+On native these are ignored; the sheet is anchored to the screen.
+
+## Dismissal
+
+Press outside or hit Escape. `dismissible={false}` turns both off, for a popover the user has to answer.
+
+Escape stops at the innermost open surface, so a popover opened from inside a dialog closes the popover and leaves the dialog up.