@oxyhq/bloom 1.0.0 → 1.0.2

package/docs/dot-grid-meter.mdx

@@ -0,0 +1,66 @@
+---
+title: DotGridMeter
+description: How many out of a total, when the total is small enough to count.
+order: 64
+---
+
+# DotGridMeter
+
+A grid of dots, some filled. It answers *how many out of how many* for a total
+the eye can actually count.
+
+```tsx
+import { DotGridMeter } from '@oxyhq/bloom/dot-grid-meter';
+
+<DotGridMeter filled={34} total={50} columns={10} accessibilityLabel="Tokens used" />
+```
+
+## Which prop decides what
+
+| prop                       | decides                                       |
+| -------------------------- | ---------------------------------------------- |
+| `filled` / `total`          | the count and the ceiling                      |
+| `columns`                   | the grid width, which sets the row count        |
+| `dotSize` / `gap`           | the geometry                                   |
+| `filledColor` / `emptyColor`| the two states                                 |
+| `accessibilityLabel`        | what is being counted — see below              |
+
+## Use it when the total is countable
+
+Thirty-four of fifty tokens, seven of ten onboarding steps, twelve of twenty
+invites. The point is that a reader can verify the number by looking — that is
+what a dot grid gives you over a bar.
+
+Over a few hundred it stops being countable and becomes a texture. Past that a
+[`StatBar`](/docs/bloom/main/stat-bar) is the honest widget: it does not
+pretend the reader can count.
+
+## `columns` decides the shape
+
+Pick a value that makes the rows read as groups — 10 across for a total of 50
+gives five clean rows of ten, which is countable at a glance. An awkward number
+leaves a ragged last row and makes the total harder to read, not easier.
+
+## Both colours matter
+
+The empty dots carry the *total*, so they must be visible. An `emptyColor` too
+close to the background turns the widget into "34 dots" with no denominator,
+which is the one thing it exists to show.
+
+## State the numbers as well
+
+`34 / 50` in text beside the grid. The dots are the shape of the answer; the
+text is the answer.
+
+## Name what is being counted
+
+The grid announces itself as a `progressbar` carrying `aria-valuenow` /
+`aria-valuemin` / `aria-valuemax`, so a screen reader reads the numbers — but
+`progressbar` takes its name from the author alone. ARIA never computes one
+from an element's contents for this role, and the contents are dots in any
+case, so without `accessibilityLabel` the meter announces "34 of 50" against
+nothing. `StatBar` gets this for free from its required `label`; a bare grid has
+no such text.
+
+Omitting it warns once in development, dev-only and never throwing. An empty or
+whitespace-only string counts as missing.

package/docs/dropdown-menu.mdx

@@ -0,0 +1,161 @@
+---
+title: DropdownMenu
+description: An action menu anchored to a trigger — a bottom sheet on native, a dropdown on web.
+order: 14
+---
+
+# DropdownMenu
+
+The menu that drops from a button. A bottom sheet on native, an anchored panel on web, one API on both.
+
+The parts are shadcn's, so a `@shadcn/ui` or `react-native-reusables` call site ports across unchanged: `DropdownMenu` owns the open state, `DropdownMenuTrigger` opens it, `DropdownMenuContent` is the surface, and the rows are `DropdownMenuItem`, `DropdownMenuCheckboxItem`, `DropdownMenuRadioGroup` / `DropdownMenuRadioItem`, `DropdownMenuLabel`, `DropdownMenuSeparator`, `DropdownMenuShortcut`, `DropdownMenuGroup` and the `DropdownMenuSub` trio.
+
+`ContextMenu` and `Menubar` publish the same row vocabulary under their own prefixes. They are one implementation, so a row behaves identically in all three.
+
+## Basic
+
+```tsx
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuLabel,
+  DropdownMenuSeparator,
+  DropdownMenuShortcut,
+  DropdownMenuTrigger,
+} from '@oxyhq/bloom/dropdown-menu';
+import { Button } from '@oxyhq/bloom/button';
+
+<DropdownMenu>
+  <DropdownMenuTrigger asChild label="Open menu">
+    <Button variant="secondary">Open menu</Button>
+  </DropdownMenuTrigger>
+
+  <DropdownMenuContent>
+    <DropdownMenuLabel>My account</DropdownMenuLabel>
+    <DropdownMenuSeparator />
+    <DropdownMenuItem onPress={openProfile}>Profile</DropdownMenuItem>
+    <DropdownMenuItem trailing={<DropdownMenuShortcut>⌘,</DropdownMenuShortcut>}>
+      Settings
+    </DropdownMenuItem>
+    <DropdownMenuItem disabled>Billing</DropdownMenuItem>
+    <DropdownMenuSeparator />
+    <DropdownMenuItem variant="destructive" onPress={signOut}>
+      Sign out
+    </DropdownMenuItem>
+  </DropdownMenuContent>
+</DropdownMenu>
+```
+
+A row dismisses the menu after it fires. Pass `keepOpen` to a row that should not — a checkbox row you expect the user to toggle twice, say.
+
+## `asChild`
+
+`asChild` is Radix's composition escape hatch and it works the same way here: the trigger's single element child *becomes* the trigger and receives the open handler plus the accessibility props. Without it, the children render inside Bloom's own pressable.
+
+```tsx
+<DropdownMenuTrigger asChild label="Actions">
+  <Button variant="icon" onPress={track}>…</Button>
+</DropdownMenuTrigger>
+```
+
+Handlers the child already carries are composed, not replaced — `track()` runs first, then the menu opens.
+
+`disabled` on the trigger is guarded the same way, at the composition layer rather than on the child alone — pass `disabled` to `DropdownMenuTrigger`, not to your own child element, or the open handler still fires.
+
+## Controlled
+
+```tsx
+const [open, setOpen] = useState(false);
+
+<DropdownMenu open={open} onOpenChange={setOpen}>
+  …
+</DropdownMenu>
+```
+
+Uncontrolled by default; pass `open` to take over. `onOpenChange` fires either way. There is no imperative control to reach for and no `close()` to call: the menu's state is one boolean, and a row closes it by returning.
+
+## Checkbox and radio rows
+
+```tsx
+<DropdownMenuCheckboxItem checked={dense} onCheckedChange={setDense} keepOpen>
+  Dense rows
+</DropdownMenuCheckboxItem>
+
+<DropdownMenuRadioGroup value={sort} onValueChange={setSort}>
+  <DropdownMenuRadioItem value="newest">Newest</DropdownMenuRadioItem>
+  <DropdownMenuRadioItem value="oldest">Oldest</DropdownMenuRadioItem>
+</DropdownMenuRadioGroup>
+```
+
+Both announce their state as `aria-checked`, which is the spelling react-native-web reads and React Native folds back into `accessibilityState` — so it reaches assistive tech on both platforms.
+
+## Sub-menus: a flyout on web, an inline disclosure on native
+
+The API is one thing on both platforms — a shadcn call site ports across unchanged — and the presentation is the platform's own, matching what each platform's upstream does.
+
+```tsx
+<DropdownMenuSub>
+  <DropdownMenuSubTrigger>Send to…</DropdownMenuSubTrigger>
+  <DropdownMenuSubContent>
+    <DropdownMenuItem>Email</DropdownMenuItem>
+    <DropdownMenuItem>Messages</DropdownMenuItem>
+  </DropdownMenuSubContent>
+</DropdownMenuSub>
+```
+
+**On web** the sub-panel flies out beside its trigger row, the way shadcn's does, and its chevron points right:
+
+- Hovering the row opens it; leaving either surface schedules a close 300 ms later, and entering either one cancels that — which is what keeps it open while the pointer travels diagonally across the gap between them.
+- Pressing the row toggles it, so a click and a touch-web tap both work.
+- <kbd>→</kbd> opens it and moves focus onto its first row; <kbd>←</kbd> closes it and returns focus to the trigger.
+- <kbd>Esc</kbd> closes the **innermost** surface first: one press shuts the sub-panel and leaves the menu open, a second shuts the menu.
+- It takes its own rank from `overlay/stack.ts` on mount, like every other surface, so it paints above the menu it opened from and carries no `zIndex` of its own.
+- It positions itself through the same `overlay/dropdown-placement` every other anchored surface uses, with `side="right"`. With no room to the right it flips to the left of the row on its own — there is no second positioner.
+
+**On native** it is an inline disclosure: the trigger expands its content in place, under the row, and the chevron swaps between down and up. react-native-reusables renders it the same way there, and a menu on native is a bottom sheet — there is nowhere for a flyout to fly to.
+
+The split is a build-time one, not a `Platform.OS` branch: `floating/menu-sub-flyout.tsx` and `floating/menu-sub-inline.tsx` are passed to `createMenuRows` by each family's own platform fork, so the web-only `FloatingPanel` never reaches a native bundle.
+
+Verified in a real browser by `scripts/verify-submenu-flyout.mjs` — jest can see none of it.
+
+## Placement (web)
+
+`DropdownMenuContent` takes `side` (`'top' | 'bottom'`, default `'bottom'`), `align` (`'start' | 'center' | 'end'`, default `'start'`), `sideOffset` and `alignOffset` — the same four Radix takes. They are preferences: the surface flips to the other side when the named one does not fit and clamps into the viewport when neither does.
+
+`side` also accepts `'left'` and `'right'`, which make the horizontal axis the one that fits, flips and clamps, and `align` the vertical one. That is how the sub-panel positions itself; a root dropdown has no use for it.
+
+On native these are ignored. The menu is a bottom sheet, which is anchored to the screen rather than to the trigger.
+
+## Naming a row that is not a plain string
+
+A row whose child is a string names itself. A row composed of elements does not:
+
+```tsx
+<DropdownMenuItem accessibilityLabel="Profile">
+  <UserIcon />
+  <Text>Profile</Text>
+</DropdownMenuItem>
+```
+
+Without it a screen reader announces the row as nothing. This is where the upstream primitive's `textValue` lands — spelled `accessibilityLabel` because in Bloom that is all it does.
+
+## Screen-reader focus
+
+On NATIVE, opening a menu moves the VoiceOver/TalkBack cursor into the sheet, and closing it returns the cursor to the trigger. Both are automatic for every Bloom surface that presents through a sheet — menus, context menus, the menubar, popovers and select — and neither needs any wiring at the call site.
+
+They are a pair on purpose. Moving the cursor in without giving it back strands it on the root view after the surface unmounts, which is worse than never moving it.
+
+The platform's own dismiss gesture works too: a two-finger Z scrub under VoiceOver, a back gesture under TalkBack. Android's hardware back already closed these, since every Bloom sheet is an RN `<Modal>`.
+
+On WEB none of this applies — the browser owns focus and the hooks return early rather than calling an API that is a no-op there.
+
+## Rows are className-first
+
+Every row is one pressable node built from Bloom's `styled()` primitives, shared by all three menu families through `floating/shared.tsx` — so the disabled treatment, the destructive colour, the pointer highlight and the ARIA state stay in one place and a fix lands in every menu at once.
+
+Its shape is a class string, not resolved numbers, because that is how the originals are built and it is the only form a consumer can override with a utility (an inline `style` outranks a class on web whatever the array order). `floating/constants.ts` holds the vocabulary: `relative flex-row items-center px-2 py-1.5 gap-2 min-h-8 rounded-xl` on a row, `pl-8 pr-2` on the two that carry an indicator, `text-sm` throughout, and a 32px minimum height. There is no `sm:` breakpoint any more — the row is the same density at every window width.
+
+Every part takes a `className` and APPENDS it to its own, so a layout class cannot strip the chrome. Two utilities for one property are then resolved by Tailwind's own emission order, exactly as in any shadcn consumer; `style` remains the unambiguous override.
+
+**A web consumer must have the Tailwind/NativeWind pipeline wired and `@source`-scanning `@oxyhq/bloom/lib`.** That was always required; it is now visible rather than subtle, because the colours moved out of inline style too.

package/docs/error-boundary.mdx

@@ -0,0 +1,72 @@
+---
+title: ErrorBoundary
+description: Containing a failure to a section instead of losing the screen.
+order: 51
+---
+
+# ErrorBoundary
+
+Catches a render error below it and shows a fallback instead of unmounting the
+tree above.
+
+```tsx
+import { ErrorBoundary } from '@oxyhq/bloom/error-boundary';
+
+<ErrorBoundary
+  title="This feed didn't load"
+  message="Your other tabs are unaffected."
+  retryLabel="Try again"
+  onError={report}
+>
+  <Feed />
+</ErrorBoundary>
+```
+
+## Which prop decides what
+
+| prop         | decides                                                     |
+| ------------ | ------------------------------------------------------------ |
+| `title` / `message` / `retryLabel` | the wording of the default fallback    |
+| `fallback`   | replaces it entirely — a node, or a function                 |
+| `onError`    | reporting; called with the error and the React error info    |
+
+## Place it where a failure should cost a section, not the screen
+
+Around a feed, a widget, a tab's content, a third-party embed. One boundary at
+the app root turns every error into a blank page, which is the outcome a
+boundary exists to prevent.
+
+The useful question is: *if this subtree fails, what should the user still be
+able to do?* Whatever the answer is, the boundary goes below it.
+
+## The function `fallback` gives you `retryCount`
+
+That is the reason to reach for it. After two or three failed retries, offering
+the button again is dishonest — the same thing will fail the same way.
+
+```tsx
+fallback={({ error, retry, retryCount }) =>
+  retryCount < 2 ? <Retry onPress={retry} /> : <Offline error={error} />
+}
+```
+
+## Write the fallback for someone who does not know what a boundary is
+
+Say what they lost and what the button will do. "This feed didn't load" is
+useful; "Something went wrong" tells them only that we noticed.
+
+Never show the error message itself in production UI. It is written for us, it
+often contains internals, and it cannot be acted on.
+
+## What it does not catch
+
+React error boundaries catch errors thrown **during render**. They do not catch:
+
+- errors in event handlers — those are just exceptions; catch them where they
+  happen and surface them with a [toast](/docs/bloom/main/toast) or an
+  [admonition](/docs/bloom/main/admonition);
+- rejected promises and async failures — the same;
+- errors in code above the boundary itself.
+
+So a boundary is a safety net for the unexpected, not the way you handle a
+failed request. A request that can fail has a designed failure state.

package/docs/fab.mdx

@@ -0,0 +1,67 @@
+---
+title: Fab
+description: The floating action button — one per screen, for the screen's primary action.
+order: 43
+---
+
+# Fab
+
+A floating button for the **one** thing a screen is mostly for: compose on a
+feed, add on a list, new message in an inbox.
+
+```tsx
+import { Fab } from '@oxyhq/bloom/fab';
+
+<Fab
+  icon={<PencilIcon />}
+  accessibilityLabel="New post"
+  onPress={compose}
+/>
+
+<Fab
+  icon={<PencilIcon />}
+  label="New post"
+  placement="bottom-right"
+  onPress={compose}
+/>
+```
+
+## Which prop decides what
+
+| prop        | decides                                                        |
+| ----------- | --------------------------------------------------------------- |
+| `icon`      | the glyph                                                       |
+| `label`     | makes it an extended FAB with visible text                      |
+| `variant`   | `primary` · `secondary` · `tertiary` · `surface`                |
+| `size`      | `small` · `medium` · `large`, or a number                       |
+| `placement` | which corner it floats in, or `static` to place it yourself     |
+| `offset`    | distance from the edges                                         |
+
+## An icon-only FAB needs `accessibilityLabel`
+
+Without it the button announces as "button" and nothing else. A pencil is not
+self-describing to a screen reader, and it is not always self-describing on
+screen either — which is what `label` is for.
+
+## One per screen
+
+A FAB claims the corner and floats above the content. Two of them are two
+primary actions, which means neither is primary, and they compete for the same
+thumb position. If a screen has several important actions, the FAB takes the
+most common one and the rest go in the content or a menu.
+
+## `placement="static"` when something else owns the position
+
+A FAB inside a scroll container, or one that has to sit above a tab bar, is
+easier to place with layout than to nudge with `offset`. `static` turns off the
+absolute positioning and leaves it to you.
+
+Remember the safe area and any bottom chrome: a FAB pinned to `bottom-right`
+with no offset lands under a tab bar on most phones, where it is unreachable
+rather than merely ugly.
+
+## Do not hide it behind scroll
+
+Hiding the FAB while scrolling down is a common pattern and a bad default: the
+action becomes unavailable exactly while the user is looking for it, and the
+reappear animation reads as a glitch. Prefer letting it stay.

package/docs/field.mdx

@@ -0,0 +1,70 @@
+---
+title: Field
+description: Label, description, error and the wiring that makes them announce as one control.
+order: 29
+---
+
+# Field
+
+`Field` wraps a control with the things around it — a label, a hint, an error —
+and, more importantly, the associations that make a screen reader read them as
+belonging to that control rather than as loose text near it.
+
+```tsx
+import { Field } from '@oxyhq/bloom/field';
+import { TextField, TextFieldInput } from '@oxyhq/bloom/text-field';
+
+<Field
+  label="Email address"
+  description="We only use this for sign-in."
+  error={errors.email}
+  required
+>
+  <TextField>
+    <TextFieldInput label="Email" value={email} onChangeText={setEmail} />
+  </TextField>
+</Field>
+```
+
+## Which prop decides what
+
+| prop          | decides                                                     |
+| ------------- | ------------------------------------------------------------ |
+| `label`       | the control's name                                           |
+| `description` | a persistent hint, shown whether or not there is an error     |
+| `error`       | the message; `null` or omitted means valid                    |
+| `required`    | the required marker and the announced requirement             |
+| `disabled`    | dims the whole group                                         |
+| `nativeID`    | the id the label and control are wired through                |
+
+## `error` is a string, not a boolean
+
+Because the message *is* the value. A boolean `hasError` forces the message to
+live somewhere else, and the two then disagree — a red border with no
+explanation, or an explanation after the user already fixed it.
+
+```tsx
+<Field error={touched ? validate(value) : null}>
+```
+
+## A description is not an error, and an error is not a description
+
+Keep both. The description says what the field is for and stays put; the error
+says what went wrong with what was typed. Replacing the description with the
+error means the user loses the instructions at the exact moment they need them.
+
+## Placeholder is not a label
+
+A placeholder disappears as soon as there is text, so a form filled in from
+autofill or a paste has no visible labels at all. `Field`'s `label` is the
+label; a placeholder is at most an example of the format.
+
+## Composition
+
+`Field` does not care what it wraps — a `TextField`, a `Switch`, a
+`SegmentedControl`, a custom control. It supplies the label/description/error
+and the id wiring; the control supplies its own role and state.
+
+For the label alone, without the surrounding structure, use
+[`Label`](/docs/bloom/main/label). For a control with attached buttons or
+prefixes, use [`InputGroup`](/docs/bloom/main/input-group) *inside* a `Field`.

package/docs/fill.mdx

@@ -0,0 +1,58 @@
+---
+title: Fill
+description: The four-line absolute-inset block, as one word.
+order: 46
+---
+
+# Fill
+
+A view pinned to all four edges of its parent. It replaces the style object
+that used to be written inline wherever a scrim, a gradient or a press layer
+had to cover its parent exactly.
+
+```tsx
+import { Fill } from '@oxyhq/bloom/fill';
+
+<View style={{ height: 180, borderRadius: 12, overflow: 'hidden' }}>
+  <Image source={cover} style={{ flex: 1 }} />
+  <Fill style={{ backgroundColor: 'rgba(0,0,0,0.45)' }} />
+  <Fill style={{ alignItems: 'center', justifyContent: 'center' }}>
+    <Text>Over the top</Text>
+  </Fill>
+</View>
+```
+
+## What it is for
+
+Writing `position: 'absolute', top: 0, right: 0, bottom: 0, left: 0` by hand
+four times in a file is how three of the four edges end up right. `Fill` is the
+same object, named.
+
+Overriding one edge still works, and the others survive:
+
+```tsx
+<Fill style={{ left: '50%' }} />   // right half only
+```
+
+## It takes its size from the parent
+
+`Fill` has no size of its own — it fills the nearest positioned ancestor. In a
+parent with no height it is invisible, not broken, which is the usual reason a
+scrim "doesn't show up".
+
+## Stacking
+
+Two fills stack in source order: the later one paints above. There is no
+`zIndex` involved, and there should not be — a scrim over a photo under a label
+is three siblings in the order you want them.
+
+## What it is not for
+
+- **An overlay surface.** A dialog, a sheet or a menu goes through
+  [`Portal`](/docs/bloom/main/portal) plus
+  [`OverlayRoot`](/docs/bloom/main/overlay), which give it a stack position and
+  an interactive root. A `Fill` at the root of a screen is a full-bleed band
+  that silently eats presses.
+- **A press layer that must not block touches.** If content underneath has to
+  stay pressable, the fill needs `pointerEvents="none"` — as a **prop**, since
+  the RN-only values are dropped when written as a style.

package/docs/fonts.mdx

@@ -0,0 +1,144 @@
+---
+title: Fonts
+description: How Bloom's typefaces reach a web bundle and a native build — and where the documented stacks and current fleet practice diverge.
+order: 58
+---
+
+# Fonts
+
+Bloom ships its own typefaces and loads them for you. `BloomThemeProvider`
+mounts `FontLoader`, which injects `@font-face` rules on web and loads the
+assets on native.
+
+```tsx
+// Nothing to do: BloomThemeProvider already does this.
+<BloomThemeProvider>…</BloomThemeProvider>
+```
+
+## What the subpath exports
+
+Almost no app imports `@oxyhq/bloom/fonts` — the provider does. Reach for it
+when you need the family stacks in a style of your own, or when you are loading
+fonts yourself (a bare React Native app with no `BloomThemeProvider`):
+
+```tsx
+import { fontFamilies, fontCssVars, FONT_ASSETS, applyFontFaces, FontLoader } from '@oxyhq/bloom/fonts';
+```
+
+| Export | What it is |
+| --- | --- |
+| `fontFamilies` | The three family STACKS (`display`, `sans`, `mono`), each with system fallbacks. The literal `fontFamily` string source on native, and the value of the CSS variables on web. |
+| `fontCssVars` | The inverse map: family name → `--bloom-font-*` custom property name. |
+| `FONT_ASSETS` | The `expo-font` map for `useFonts()`. Populated under Metro only — see below. |
+| `applyFontFaces()` | Injects the `@font-face` rules and the `:root` variables. Web only, idempotent, SSR-safe. |
+| `FontLoader` | The component `BloomThemeProvider` mounts. `enabled`, `fallback`, `children`. |
+
+`fontFamilies.display` and `.sans` both lead with **BlomusModernus**;
+`.mono` leads with **Geist Mono**. On native, `FontLoader` prepends
+`{ fontFamily: 'BlomusModernus' }` to `Text.defaultProps.style` once the assets
+report loaded, so every `<Text>` in the app inherits it — which is why an app
+setting its own `fontFamily` is overriding Bloom rather than complementing it.
+
+## A fourth family ships and registers unconditionally: Inter
+
+Bloom bundles Inter alongside BlomusModernus and Geist Mono, on both platforms,
+and loading it is not gated the way you'd expect:
+
+- `FONT_ASSETS` (native) requires `InterVariable.ttf` (879,708 bytes) under the
+  key `Inter`. `FontLoader.native.tsx` calls `useFonts(FONT_ASSETS)`
+  unconditionally — per the Rules of Hooks the hook has to fire whether or not
+  `<BloomThemeProvider fonts={false}>` is set — so Inter is bundled into the
+  native binary and loaded into the platform font registry for every consumer
+  that mounts `BloomThemeProvider`, regardless of that prop.
+- `apply-font-faces.web.ts` injects an `@font-face` rule for `'Inter'` from
+  `InterVariable.woff2` (48,256 bytes) alongside the other two families. This
+  half *is* gated on the `fonts` prop (default `true`).
+
+**But `Inter` is not a member of `fontFamilies.display`, `.sans` or `.mono`** —
+those three stacks lead with BlomusModernus and Geist Mono only, as shown
+above. There is no exported constant that names Inter; a consumer reaches it
+only by writing the literal string `'Inter'` itself.
+
+In practice, several apps in the fleet do exactly that. Mention's
+`packages/frontend/global.css` and `tailwind.config.js`, and CrowdSource's
+`console` and `reviewer` apps, set `--font-sans: Inter` / `sans: ['Inter', …]`
+directly. Alia's `packages/app/tailwind.config.js` does the same — and ships
+no font file of its own for it: the built `InterVariable-*.woff2` in
+`alia-canvas`, `alia-console` and `alia-gateway-admin` is byte-identical
+(md5 `260c81a4759baf163c025001c4f27872`, 48,256 bytes) to Bloom's own
+`src/fonts/assets/InterVariable.woff2`. This resolves today only because
+Bloom happens to register the family, unconditionally, on both platforms.
+
+`'Inter-Regular'`, which appears as a fallback in Mention's and CrowdSource's
+`font-family` declarations (`font-family: 'Inter', 'Inter-Regular', sans-serif`),
+names nothing Bloom — or anything else in this repo — ever registers. Only the
+bare family `Inter` is registered, as a single variable face. That fallback
+entry has been dead since it was written; on a machine without a
+system-installed `Inter-Regular` it just falls through to the next name in the
+stack.
+
+Whether selecting `'Inter'` by hand is a supported way to reach it, or several
+apps happening to line up with a family Bloom bundles for its own reasons, is
+not settled anywhere in this repo. Treat it as an open question, not a green
+light or a ban — and treat any *other* hand-set literal the same way `'Inter-Regular'`
+turned out: it either matches a family one of the four platform conditions
+above actually registers, or it silently falls back to the system face.
+
+## Four ways in, one surface
+
+`./fonts` is resolved by export condition, and each condition lands on a barrel
+whose members are already the right implementation for that platform. This is
+the whole mechanism — there is no runtime platform check anywhere in the family:
+
+| Condition | Barrel | `applyFontFaces` | `FONT_ASSETS` | `FontLoader` |
+| --- | --- | --- | --- | --- |
+| `react-native` (Metro) | `index.ts` | no-op stub | the Metro asset map | loads `.ttf` via `useFonts` |
+| `browser` (Vite, webpack, Metro-web) | `index.web.ts` | injects `@font-face` | empty | injects on first render |
+| `node` (SSR, prerender, tooling) | `index.node.ts` | no-op stub | empty | renders children |
+| `import` / `require` | `index.ts` | no-op stub | empty | — |
+
+The `node` condition is load-bearing, not tidiness: the web `FontLoader` imports
+`apply-font-faces.web`, which reaches `font-urls.web`'s `.woff2` imports. Node
+hands a `.woff2` to the JS parser, so merely LOADING that module throws a
+`SyntaxError` — before any `typeof document` guard inside the function can run.
+
+Every barrel names its platform-forked siblings OUTRIGHT (`./apply-font-faces.web`,
+`./font-assets.web`) rather than leaving the extension to the bundler. Vite does
+no platform-extension resolution, so an extensionless specifier there falls
+through to the default file and the fonts silently stop being injected.
+
+## The `.woff2` files are assets, not base64
+
+`font-urls.web.ts` imports the four files so the consuming bundler emits them
+as content-hashed assets. **Never inline them as base64 again** — that put
+~219 KB gzip into every web entry bundle and made the fonts uncacheable, since
+a font embedded in JS cannot be cached as a font.
+
+The one consumer requirement is `woff2` in Metro's `assetExts`, which
+`@oxyhq/app-preset` registers fleet-wide. Bundlers that already treat an asset
+import as a URL (Vite, Rollup, webpack 5) need nothing.
+
+## Two things that look like cleanups and are not
+
+**`apply-font-faces.ts` must stay an empty stub with no imports.** It is the
+neutral default; the web variant is `apply-font-faces.web.ts`. Give the default
+real imports and Metro bundles a second, unusable copy of the font machinery
+into every native app.
+
+**Do not fork `FontLoader` into a `.web` plus a neutral default.**
+`BloomThemeProvider` imports it by *relative* path, and export conditions do
+not apply to relative specifiers — so Vite would silently take the neutral
+default and stop injecting `@font-face` for every web consumer. `FontLoader.tsx`
+IS the web implementation; `FontLoader.native.tsx` and `FontLoader.node.tsx` are
+selected by Metro's platform extensions and by the `node` condition respectively.
+
+## Verifying that fonts are actually on
+
+This is a system that fails by looking fine: a missing `@font-face` falls back
+to a system face rather than erroring. Bloom's own Storybook ran with
+`fonts={false}` for months and every story looked plausible.
+
+Check the computed `font-family` on real text, not that the provider is
+mounted. On web, `applyFontFaces()` goes through a CONSTRUCTED stylesheet
+(`adoptedStyleSheets`), so there is no `<style id="bloom-fonts">` element to
+look for — read the document's adopted sheets, or just measure the text.