# UI package agent guide

`@colineapp/ui` is the public React component and bridge-provider package for
tier-2 Coline Apps. It is the app author's UI layer; it is not the platform's
internal component library.

## Required app setup

```tsx
import { createRoot } from "react-dom/client";
import {
  Button,
  ColineAppProvider,
  useColine,
  useColineQuery,
} from "@colineapp/ui";
import "@colineapp/ui/styles.css";

function Home() {
  const coline = useColine();
  const items = useColineQuery(
    (capabilities) => capabilities.files.list({ limit: 100 }),
    [],
  );
  return <Button onClick={() => items.refetch()}>Refresh</Button>;
}

const root = document.getElementById("root");
if (root) {
  createRoot(root).render(
    <ColineAppProvider>
      <Home />
    </ColineAppProvider>,
  );
}
```

The package requires React 19 and ReactDOM 19 as peer dependencies. The
scaffold installs them for app authors. `ColineAppProvider` is mandatory
before using `useColine`, `useColineContext`, `useColineQuery`, or
`useColorScheme`; it intentionally renders nothing until the bridge connects.

## Data and sandbox rules

- All app data goes through the injected `coline.*` capability client.
- Do not use `fetch`, localStorage, cookies, direct API routes, or credentials
  in a sandboxed app. Network access belongs behind `coline.net.fetch` and the
  manifest allowlist.
- `useColineQuery(loader, deps)` is a small loading/error/refetch helper, not a
  cache. Keep loaders bounded and put stable values in `deps`.
- Use host theme tokens and the exported components. Do not hardcode light-only
  colors or invent a second provider.

## Component contract

The public barrel exports the provider/hooks plus accessible components such
as `Button`, `Card`, `Input`, `Textarea`, `Badge`, `Dialog`, `Select`,
`Checkbox`, `Switch`, `Tabs`, `Table`, `Skeleton`, and `Tooltip`. Check the
component source and declaration output before documenting a new prop.

The client bundle is built by Coline. The app submits `main.tsx` and its
source files; it does not submit `node_modules` or install packages in the
sandbox. Keep client imports limited to the scaffold dependencies and app
source.

## Verification and release

- Run `pnpm --filter @colineapp/ui typecheck` after component/provider changes.
- Keep CSS export and component export changes together.
- Preserve React peer dependency ranges and the `./styles.css` export.
- Update README examples and the scaffold skill when an app-facing contract
  changes. The generated app must be able to use the documented API after a
  clean `npm install`.