# 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 CLI bundles `main.tsx`, installed client dependencies, and imported CSS.
Coline rebuilds the uploaded artifact; the sandbox does not install packages.
Browser-compatible npm dependencies can be added to the app package.

## 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`.

## SDK 0.4 / CLI 2.4 workflow

Run `coline-app check` before pushing: it checks types, the manifest, hosted logic,
and the React bundle without uploading. `dev --internal` updates one development
version; install it in the workspace and reload after changes. The CLI bundles
from the app's installed dependencies and preserves imported CSS and inline assets.
CLI 2.5 compiles app-specific Tailwind v4 and ordinary CSS automatically.
Import UI styles, then app.css; use complete class names. Local `preview` uses
the public test workspace and sandbox bridge, requires no credentials, and can
capture light/dark/mobile/error states with `--screenshots <directory>`.

The starter includes a React home and editor, tree mobile fallback, and a tool.
Use `coline.tools.invoke` or `actions.invokeTool` to run the same declared tool
from UI that Kairo runs. Save with `expectedVersion` to detect concurrent edits.
Homes/editors can write within grants; previews and server render handlers cannot.
`createTestWorkspace(app).client()` tests the interactive contract and
`grantedPermissions` simulates revoked consent.

New `tasks`, `calendar`, `messages`, and `references` capabilities require their
explicit manifest permissions and retain the invoking user's workspace access.
Use `files.list({ scope: "workspace" })` for shared files; document writes stay
with the owning app. Collections are install-private. Code integration and a
native mobile React runtime are separate work.

`src/live-collection.ts` wraps the SDK's canonical live-record implementation.
Keep state/conflict/sync logic in the SDK; React owns only subscriptions and
lifecycle. Inline serializable query objects must not restart the view on each
render. React Strict Mode cleanup/start must remain supported. Never infer record
permission from optimistic state or broadcast private fields to an install room.