# BeeUI — full agent context

> Expanded stable-API, setup, compatibility, and architecture-contract detail for coding agents. Companion to llms.txt (compact index), llms-components.txt (component inventory), and llms-patterns.txt (patterns).

STATUS: BeeUI is pre-1.0 and UNPUBLISHED. No `@beemvp/beeui-*` package or CLI is on npm, no `v1.0.0` tag or GitHub Release exists, and the repository is private by owner decision. Package/CLI names and install commands below are release-ready-but-not-published targets, not live registry commands. Do not tell a user to `npm install @beemvp/beeui-ui` or `npx @beemvp/beeui-cli` yet — those resolve to nothing today. The working, in-repo path is the source-ownership CLI (`pnpm beeui -- add <component>`).

## What BeeUI is
BeeUI is a reusable, mobile-first React Native UI foundation for long-lived client apps. The public component API stops at `@beemvp/beeui-ui`; applications should not need to know the styling engine. Web support is additive and native ergonomics remain first-class. See [docs/architecture.md](docs/architecture.md).

## Packages (all unpublished / pre-1.0, one lockstep version)
- `@beemvp/beeui-core` v20260902.0.0 — Engine-neutral utilities (class-name merging, anchored-overlay geometry) shared by @beemvp/beeui-ui. No React, React Native, or Expo dependency. [unpublished (publishConfig.access=public prepared)]
- `@beemvp/beeui-tokens` v20260902.0.0 — BeeUI's design-token system: semantic color/spacing/typography/motion contracts and the canonical Uniwind/Tailwind theme CSS. [unpublished (publishConfig.access=public prepared)]
- `@beemvp/beeui-ui` v20260902.0.0 — Typed React Native + Web components built on @beemvp/beeui-core and @beemvp/beeui-tokens, styled through Uniwind/Tailwind. [unpublished (publishConfig.access=public prepared)]

`@beemvp/beeui-core`, `@beemvp/beeui-tokens`, and `@beemvp/beeui-ui` share one lockstep version and are released together (ADR-011 D6). Package manifests declare `publishConfig.access=public` + provenance but remain unpublished; `exports` maps ship dual ESM+CJS with `.d.ts`, a `react-native` condition for Metro, `browser`/`default` for Web, and `@beemvp/beeui-tokens/theme.css` for the Web theme.

## Consumption models
1. Centralized packages (release-ready target, NOT on npm): `npm i @beemvp/beeui-ui` pulls `@beemvp/beeui-core` + `@beemvp/beeui-tokens`; import components from `@beemvp/beeui-ui`; wire Web theme with `@import '@beemvp/beeui-tokens/theme.css'`.
2. Source ownership (works today, repo-local): `pnpm beeui -- add <component>` copies component source in-tree and rewrites `@beemvp/beeui-core` imports via `rewrite-beeui-core-cn` / `rewrite-beeui-core-module`. Run `pnpm beeui -- list` for the canonical component list (generated from registry/registry.json). Future published CLI: `@beemvp/beeui-cli` (binary `beeui`), `npx @beemvp/beeui-cli add <component>` — never `npx beeui` (the unscoped name is an npm tombstone; see [docs/distribution-names.md](docs/distribution-names.md)).

See [docs/decisions/011-distribution-architecture.md](docs/decisions/011-distribution-architecture.md) and [docs/registry-cli.md](docs/registry-cli.md).

### Consuming the packages before release (pnpm pack tarballs)
The centralized model above is a target, but a new, standalone external app can already consume it **today** without npm — as local tarballs, the same package boundary CI's `scripts/verify-web-consumer.sh` / `scripts/verify-bare-consumer.sh` and the checked-in starters use (never a `workspace:*` link or a hand-copied `dist/`). Steps: (1) build the packages once from the repo root (`pnpm build`); (2) pack `@beemvp/beeui-core`, `@beemvp/beeui-tokens`, and `@beemvp/beeui-ui` into `*.tgz` files — the starters do this with [examples/scripts/pack-beeui-packages.mjs](examples/scripts/pack-beeui-packages.mjs), which runs `pnpm pack` per package; (3) install the tarballs into the consumer with `npm install --save-exact <core.tgz> <tokens.tgz> <ui.tgz>`, which pins them as `"@beemvp/beeui-ui": "file:….tgz"` dependencies. This resolves the real package `exports` maps and the Web theme CSS exactly as a published install would, so no fictional npm entry is needed. Worked, buildable reference: [examples/web-consumer](examples/web-consumer) and [examples/README.md](examples/README.md).

## Quick start (repository)
```bash
corepack enable
pnpm install --frozen-lockfile
pnpm showcase   # then press i (iOS), a (Android), or w (Web)
```
Verification: `pnpm check` (typecheck + tests), `pnpm release:verify` (package gate), `pnpm --dir apps/visual-regression test` (browser QA). See [README.md](README.md).

## Provider and safe-area setup
Wrap the app root in `BeeUIProvider` (installs safe-area measurement, the Toast runtime, and the shared anchored-overlay runtime). `SafeArea` assigns explicit `top`/`bottom`/`left`/`right` edge ownership; `Screen`, `AppHeader`, and `BottomActionBar` never add insets themselves. See [apps/docs/src/content/docs/getting-started/provider-safe-area.md](apps/docs/src/content/docs/getting-started/provider-safe-area.md).

## Web bundling (Vite + react-native-web)
`@import '@beemvp/beeui-tokens/theme.css'` supplies the semantic tokens but is not, by itself, a Web build. A from-scratch Vite + react-native-web app needs a specific plugin stack and a Tailwind/Uniwind CSS entry; get it wrong and the app either fails to resolve `react-native` or builds **unstyled**. The tested stack:
- `vite.config.ts` — three plugins, in this order: `rnw()` from `vite-plugin-rnw` (resolves `react-native` → `react-native-web`), `tailwindcss()` from `@tailwindcss/vite`, and `uniwind()` from `uniwind/vite` (passed `cssEntryFile` + `dtsFile`).
- A CSS entry (e.g. `src/global.css`) imported once from the app entry, declaring in order:
```css
@import 'tailwindcss';
@import 'uniwind';
@import '@beemvp/beeui-tokens/theme.css';
@source '../node_modules/@beemvp/beeui-core/src';
@source '../node_modules/@beemvp/beeui-ui/src';
```
The `@source` globs are **required**: Tailwind/Uniwind only emit utility classes they can statically discover, and BeeUI's classes live inside the installed packages' `src`. Omit them and the build succeeds but ships with no BeeUI styling. Pinned/tested versions for every dependency in this stack are in [docs/compatibility-matrix.md](docs/compatibility-matrix.md); the complete buildable reference is [examples/web-consumer](examples/web-consumer) ([vite.config.ts](examples/web-consumer/vite.config.ts), [src/global.css](examples/web-consumer/src/global.css)). Web support boundaries: [docs/web-support-contract.md](docs/web-support-contract.md).

## Runtime theme switching (app-owned light/dark)
Brand and density live in tokens (`@import` the theme, ADR-001), but the **app-level** switch between light and dark at runtime is owned by the application and driven through Uniwind — not a BeeUI component. Import from the `uniwind` package: `Uniwind.setTheme(name)` changes the active theme globally, and `useUniwind()` reads the current `{ theme }` (and `hasAdaptiveThemes`) so the app re-renders. The valid runtime-theme names are exported from `@beemvp/beeui-tokens` as `beeRuntimeThemeNames` (`light`, `dark`, `violet-light`, `violet-dark`); `Uniwind.setTheme('light')` / `Uniwind.setTheme('dark')` is the common case. This is a single small piece of app state deciding *which* value BeeUI's existing theme runtime uses — not a second theme authority. To theme one subtree independently of the app theme, use the `BeeThemeScope` component (a public `@beemvp/beeui-ui` export) instead of a second `setTheme` path. See [docs/theming.md](docs/theming.md) and the cookbook's Recipe F in [docs/ai-agent-cookbook.md](docs/ai-agent-cookbook.md).

## Architecture invariants (do not violate)
- Stable behavior/semantic/variant APIs are independent of Uniwind, Expo, routers, storage, networking, and business logic.
- Components consume semantic tokens (`bg-primary`, `text-foreground`, `border-border`); never literal brand colors. Every semantic token exists in every theme.
- `className` is an optional current-engine escape hatch, not a portability guarantee; engine-only bridge props stay internal.
- No duplicate theme, overlay, focus, direction, or state authority. One application-root overlay runtime; nested providers reuse it.
- Tailwind/Uniwind utilities must be statically discoverable — never construct `bg-${x}` dynamically.
- Controlled primitives (Checkbox, Radio, RadioGroup, Switch, Tabs, SegmentedControl, and others) require their change callback; enabled usage without it warns in development.
- Accessibility, RTL/logical direction, large text, high contrast, and reduced motion are part of component correctness.
See [AGENTS.md](AGENTS.md) and [docs/architecture.md](docs/architecture.md).

## Non-goals (explicit)
BeeUI does not build or bundle a styling compiler, router, backend, state library, form framework, chart framework, data-grid, or virtualization engine to match another ecosystem's feature list. It owns no fetching, navigation, auth, or persistence. Timezone/business-calendar rules stay with the application (ADR-008). Table is a primitive family, not a data grid (ADR-007). Select has no Sheet mode or virtualization for 1.0 (ADR-010).

## Overlay model (summary)
- Modal-class `Dialog`/`AlertDialog` use React Native core `Modal`. `DialogContent` defaults to `overFullScreen` (transparent); `fullScreen`/`pageSheet`/`formSheet` are non-transparent so RN honors the presentation.
- Anchored `Popover`/`DropdownMenu`/`Select`/`Tooltip` share one non-modal geometry/runtime/portal/dismiss kernel installed by `BeeUIProvider`.
- Portal transport: Web `ReactDOM.createPortal`; native New Architecture `react-native-teleport`; defensive legacy fallback (does not preserve consumer context).
- Global dismissal targets the deepest active scope via semantic depth, independent of React effect order. Native measurement uses latest-request-wins generation guards.
- `Toast` is a separate transient-notification runtime (not modal, not anchored).
See [docs/anchored-overlays.md](docs/anchored-overlays.md).

## Platform / compatibility boundaries
- Targets React Native first: Expo, Expo prebuild/dev builds, bare RN, and documented RN Web. Expo-specific APIs live in apps/adapters, never core packages.
- Pinned/tested versions (React, React Native, Expo SDK, react-native-web, Tailwind, Uniwind, safe-area-context, teleport) are the authority in [docs/compatibility-matrix.md](docs/compatibility-matrix.md); Web support boundaries in [docs/web-support-contract.md](docs/web-support-contract.md).
- iOS `pageSheet`/`formSheet` presentation is EXPERIMENTAL for 1.0 (compile + deterministic evidence only; live placement/swipe is a device gate). Compilation/browser evidence never proves full native runtime behavior.

## Accessibility
Accessibility roles/names/states/focus/keyboard are component correctness, not an add-on. Web gets real focus traps (Dialog/Sheet), listbox/menu keyboard semantics, and `aria-*` relationships; native uses RN semantic roles and merged hints where no equivalent role exists. VoiceOver/TalkBack claims require device evidence. See [docs/accessibility-contract.md](docs/accessibility-contract.md).

## Architecture decision records
- [ADR-001 styling-engine](docs/decisions/001-styling-engine.md): Uniwind + Tailwind v4 as the current, replaceable styling engine behind stable APIs.
- [ADR-002 overlay-behavior](docs/decisions/002-overlay-behavior.md): Modal-class vs anchored overlays use different behavior primitives.
- [ADR-003 native-measurement-timeout](docs/decisions/003-native-measurement-timeout.md): Bounded native measurement completion and deterministic fallback.
- [ADR-004 direction-architecture](docs/decisions/004-direction-architecture.md): One stateless LTR/RTL resolver; BeeUI reads ambient direction, never writes it.
- [ADR-005 tooltip-contract](docs/decisions/005-tooltip-contract.md): Tooltip is a non-interactive contextual disclosure, not a click menu.
- [ADR-006 sheet-gesture-engine](docs/decisions/006-sheet-gesture-engine.md): Sheet: @gorhom/bottom-sheet on native, BeeUI Web overlay on Web; no drag-parity claim.
- [ADR-007 table-datatable-architecture](docs/decisions/007-table-datatable-architecture.md): Table is a composable primitive family, not a data-driven grid.
- [ADR-008 datetime-architecture](docs/decisions/008-datetime-architecture.md): Timezone-free, Intl-driven, single-date-selection value contracts.
- [ADR-009 slider-1-0-decision](docs/decisions/009-slider-1-0-decision.md): Slider scope decision for 1.0.
- [ADR-010 select-presentation-1-0-decision](docs/decisions/010-select-presentation-1-0-decision.md): Select presentation scope for 1.0 (no Sheet mode / virtualization).
- [ADR-011 distribution-architecture](docs/decisions/011-distribution-architecture.md): Public distribution model: three scoped packages + source-ownership CLI, prepared not published.

## Registry / source ownership
[registry/registry.json](registry/registry.json) is the machine-readable source of 70 items: 62 public components, 1 public theme, and internal utilities (core-cn, core-overlay, field-context, form-group-context, overlay-runtime, use-direction, use-required-callback-warning). Each item declares source files, transforms, registry dependencies, and peer dependencies. Component-to-symbol mapping is verified against [packages/ui/src/index.ts](packages/ui/src/index.ts) at generation time.

## Documentation map
- AI-agent contract + prompt cookbook: [docs/ai-agent-cookbook.md](docs/ai-agent-cookbook.md)
- Authority index: [docs/README.md](docs/README.md)
- Getting started: [Expo](apps/docs/src/content/docs/getting-started/expo.md) · [bare RN](apps/docs/src/content/docs/getting-started/bare-react-native.md) · [Web](apps/docs/src/content/docs/getting-started/web.md)
- CLI: [apps/docs/src/content/docs/cli/index.md](apps/docs/src/content/docs/cli/index.md)
- Components site: [apps/docs/src/content/docs/components/index.md](apps/docs/src/content/docs/components/index.md) (deep dives: [Table](apps/docs/src/content/docs/components/table.md), [Calendar/DatePicker](apps/docs/src/content/docs/components/calendar-date-time.md))
- Performance: methodology [docs/benchmark-harness.md](docs/benchmark-harness.md) · baseline report [docs/performance-baseline-report.md](docs/performance-baseline-report.md) · package/bundle footprint [docs/bundle-footprint-baseline.md](docs/bundle-footprint-baseline.md) · docs site [apps/docs/src/content/docs/performance/index.md](apps/docs/src/content/docs/performance/index.md)
- Release policy: [docs/release.md](docs/release.md) · Changelog: [CHANGELOG.md](CHANGELOG.md) · License: [LICENSE](LICENSE) (MIT)

Generated by scripts/generate-llms-txt.mjs from registry/registry.json, packages/ui/src/index.ts, and packages/*/package.json. Do not edit by hand; run `pnpm llms:generate`.