# GPUI Box

> Independent GPUI framework distribution plus a product-neutral component,
> semantic automation, and visual-test kit. Not an official Zed project.

Cargo package `gpui-box` imports as `gpui`; `gpui-box-kit` imports as
`gpui_kit`. Use these aliases and never mix Zed GPUI packages into the graph.
All publishable packages are crates.io-ready; Zed source is filtered into this
repository rather than linked as a Git dependency.

## Read first

1. `docs/api-index.json`: generated exact component signatures and scenes.
2. `AGENTS.md`: enforced repository rules.
3. `docs/design-principles.md`, `docs/compatibility.md`, and `PROVENANCE.md`.

Prefer generated API facts over prose. Physical paths and internal workspace
aliases containing `gpui-kit` are implementation details, not public package
identity.

## Rules

1. Library-authored visible text uses `gpui_kit::strings::StringKey`; caller
   text remains caller-owned.
2. Repeated color, spacing, radius, typography, motion, and effects come from
   `crates/gpui-kit-tokens/tokens/*.json` through the theme.
3. Loading, Empty, Unavailable, Error, and Ready remain distinct. Refresh
   failure preserves verified data; disabled controls install no handler.
4. Every action/assertion target has a stable semantic id based on business
   identity, never list position.
5. Components read caller data, emit caller actions, and hold visual transient
   state only.

## Validate

```bash
cargo run -p xtask -- gate
cargo run -p xtask -- gate only <scene>
cargo run -p xtask -- headless check <scene>
cargo run -p gpui-box-gallery -- --scene badge --theme studio-dark
cargo run -p xtask -- package plan
cargo run -p xtask -- package check
```

Inspect every changed PNG before capture. macOS, Linux, and Windows each have
active renderer-specific CI evidence; WASM is single-threaded and has explicit
accessibility limits. See `docs/compatibility.md`.

## Generated artifacts

Do not hand-edit `docs/api-index.json`, `docs/token-reference.md`,
`docs/strings-allowlist.txt`, or headless PNGs. Their `xtask` generate/capture
commands own them.

The checkout-backed `gpui-box-mcp` reads `GPUI_BOX_ROOT` or discovers upward
from cwd. `render_scene` requires the complete checkout. The hosted static
catalog is <https://gpui-box.origingame.dev>.

References: `docs/components.md`, `docs/component-contracts.md`,
`docs/coverage.md`, `docs/truthful-ui.md`, `docs/token-model.md`,
`docs/semantic-automation.md`, `docs/accessibility.md`,
`docs/screenshot-testing.md`, `docs/mcp.md`, and `docs/releasing.md`.