# jev-ui

> React components that resolve which component to render, how to order a list, and
> whether to show an affordance — from calibrated judgments returned by TypeSafe’s Jev.

- `<Branch>` — Choice with a no-match outcome; picks one subtree.
- `<Rank>` — Choice or one Score per item; orders, filters, truncates a candidate set.
- `<Gate>` — Noul; shows an affordance when a condition holds.
- `useScore` — a graded dimension that drives props rather than a subtree.

---

# Getting started

> Install, wire a Server Action, and render your first judgment.

jev-ui resolves three kinds of interface question from calibrated judgments: which component to render, how to order a list, and whether to show an affordance. A fourth, `useScore`, answers how much — you describe a scale in words and get back a number to use as an ordinary prop. The model returns typed answers with probabilities; your code decides what to do with them.

## Install

```bash
bun add jev-ui
# npm install jev-ui · pnpm add jev-ui · yarn add jev-ui
```

## Add your key

The key never reaches the browser. Put it in the environment file at the root of your app — Next.js loads it with no extra tooling, and so does bun.

```bash
# .env
TYPESAFE_API_KEY=apikey-...
```

> Add that file to your .gitignore before you paste anything into it. With no key the library falls back to the replay transport, so a checkout without one still runs against recorded fixtures rather than crashing.

## Wrap your app in the provider

`jev-ui/action` is a ready-made Server Action. The key is read there, on the server — the browser never sees it, and because the client passes only decisions and data, it cannot be turned into a general proxy to your key.

```tsx
// app/providers.tsx
'use client';
import { JevProvider } from 'jev-ui';
import { askJev } from 'jev-ui/action';

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <JevProvider resolve={askJev} state={{ app: { role: 'analyst' } }}>
      {children}
    </JevProvider>
  );
}
```

## Configuration

Everything is environment-driven, so the common case needs no code of your own.

| variable | default | what it does |
| --- | --- | --- |
| `TYPESAFE_API_KEY` | — | Your key. Server-side only. |
| `JEV_TRANSPORT` | `live` with a key, else `replay` | `live`, `record`, `replay`, `mock`, `auto` |
| `JEV_MODEL` | `jev-latest` | Model id to send |
| `JEV_FIXTURES_DIR` | `fixtures` | Where `record` writes and `replay` reads |

Write the action yourself when you need something the environment cannot express — a custom transport, per-request model selection, or your own pricing table:

```ts
// app/actions.ts
'use server';
import { createResolver } from 'jev-ui/server';

const resolve = createResolver({ model: 'jev-1.13.0', pricing: myRates });

export async function askJev(decisions, state) {
  return resolve(decisions, state);
}
```

## Render a judgment

```tsx
'use client';
import { Branch, Option } from 'jev-ui';

export function Answer({ question }: { question: string }) {
  return (
    <Branch
      ask="Which view best answers the question in `data.question`?"
      data={{ question }}
      minConfidence={0.5}
    >
      <Option k="chart" when="The question is about a trend across many time periods.">
        <RevenueChart />
      </Option>
      <Option k="table" when="The question needs exact per-row numbers.">
        <RevenueTable />
      </Option>
      <Option fallback>
        <RevenueTable />
      </Option>
    </Branch>
  );
}
```

> The `when` text is the single highest-leverage string in the component. It becomes the model's criteria, and a bare key like "chart" gives it nothing to reason about.

## The rules worth knowing up front

- The judgment picks presentation; code owns actions. Nothing here should submit a form, spend money, or delete a row.
- The library collects two things on its own — `recent_actions` and `time_spent`. Everything else goes in `app`, with whatever keys you like, and a question reads it by naming the path: `app.tier`.
- Every judgment registered in one render pass becomes one request, because the state is ingested once for all of them.
- Typed output guarantees the interface, not the truth. Always give a Branch a fallback and a confidence floor.

---

# Branch

> Pick one subtree out of several, with a no-match outcome and a confidence floor.

Branch asks a Choice question and renders the matching child. It is the right primitive when the options are unordered and exactly one should win.

```tsx
<Branch
  ask="Which view best answers the question in `data.question`?"
  data={{ question }}
  minConfidence={0.5}
  onResolved={(cost) => console.log(cost.shareUsd)}
>
  <Option k="line" when="The question is about a trend across many time periods.">
    <LineChart />
  </Option>
  <Option k="table" when="The question needs exact per-row numbers.">
    <Table />
  </Option>
  <Option fallback>
    <Table />
  </Option>
</Branch>
```

## Props

| prop | type | what it does |
| --- | --- | --- |
| ask | string | The question. Backticked paths scope which state it receives. |
| data | Json | Local state for this judgment, read as `data.*`. |
| minConfidence | number | Below this, the fallback renders instead of the winner. |
| pending | ReactNode | Rendered while resolving. Defaults to the fallback. |
| onVerdict | (v) => void | The selected key, confidence, distribution, and why. |
| pick | Channel[] | Narrow which state channels it receives. Default: all of them. |
| onResolved | (cost) => void | What the request that answered this Branch cost. |
| id | string | A readable id for the Inspector. Does not affect fixtures. |

## How it becomes a question

| your code | the question object |
| --- | --- |
| ask="…" | instructions |
| <Option k="line" when="…"> | criteria.line |
| (automatic) | criteria.__none__ |
| data={{ … }} | state.data.<id> |
| minConfidence, fallback | never sent — applied to the answer in code |

## When the fallback renders

- Confidence is below minConfidence — the model reports it is not sure, so do not act on a guess.
- The model picked the no-match option, meaning none of your options fit the state.
- The judgment failed outright. The failure is recorded and visible in the Inspector rather than swallowed.

> Low confidence on a Choice often means no option is a clear winner, not that the model is broken. Several acceptable alternatives spread probability too — a harmless preference does not need a high floor.

---

# Rank

> Order, filter, and truncate a candidate set. Two modes that answer different questions.

Rank takes candidates your code already has and puts them in order. Typeahead is not a separate primitive — it is Rank with take.

## compete — one Choice over the candidates

Probabilities sum to one, so something always wins even when nothing fits. Right for "which one did they mean": a command palette, a typeahead, a next-action menu.

```tsx
<Rank
  items={candidates}
  idOf={(c) => c.id}
  labelOf={(c) => c.label}
  mode="compete"
  take={4}
  pinTop={2}
  ask="Which of these commands did the user mean by what they typed in `query`?"
>
  {(ranked) => ranked.map(({ item, score, pinned }) => <Row key={item.id} … />)}
</Rank>
```

## grade — one Score per candidate

Each item gets its own Score question, fanned out into the same request. Those scores are comparable across items and across requests, which compete mode cannot be: a per-page Choice re-normalizes, so page two cannot be ranked against page one.

```tsx
<Rank
  items={cards}
  idOf={(c) => c.id}
  labelOf={(c) => c.title}
  mode="grade"
  levels={['Unrelated', 'Same area', 'Clearly useful', 'Exactly what they need']}
  minScore={0.5}
  ask="How well does the card in `data.item` match what the person has been doing, per `recent`?"
>
  {(ranked) => …}
</Rank>
```

## Choosing a mode

| you need | mode |
| --- | --- |
| One intended item out of a shortlist | compete |
| To drop items that do not fit at all | grade — compete always has a winner |
| To rank a second page against the first | grade — compete re-normalizes per request |
| A score you can threshold or reuse as a feature | grade |

## Shaping the result in code

- pinTop holds the leading items in place. Reordering a menu fights muscle memory.
- take truncates after ranking.
- minScore drops weak matches, in grade mode only.
- Changing any of these re-derives from the answer already in hand and spends no new request — the evidence and the question have not changed.

---

# Gate

> Show an affordance when a condition holds. A Noul, read as a probability.

```tsx
<Gate
  ask="Does the shipment in `data.order` cross an international border?"
  data={{ order }}
  threshold={0.6}
>
  <CustomsFields />
</Gate>
```

| prop | type | what it does |
| --- | --- | --- |
| ask | string | A yes/no condition about the state. |
| threshold | number | Probability at or above which the gate opens. Default 0.5. |
| otherwise | ReactNode | Rendered when the gate stays closed. |
| onProbability | (p) => void | The raw probability, for your own logic. |

> A Noul near 0.5 means yes and no are equally likely — it does not mean "medium intensity". If you want intensity, you want a Score with defined levels.

## Gates add; they do not hide

Use a Gate to reveal an optional field, a hint for someone who looks stuck, or an advanced panel. Do not use one to hide primary content: content removed by a judgment is an accessibility and SEO problem, and it is invisible to exactly the person who needed it.

## The gate stays closed while resolving

An affordance that flashes in and then out is worse than one that arrives late, so nothing renders until the answer is in.

---

# State

> Three layers, who owns each, and why a question only sees part of it.

| layer | who sets it | read in an ask as |
| --- | --- | --- |
| ambient | the library, from tracked activity | `recent_actions` and `time_spent` |
| scope | you, at the provider | `app.*` — any keys you like |
| local | you, at the call site | `data.*` |

They merge local over scope over ambient, and each layer is namespaced so they cannot collide. The library only collects the two things it can collect on its own — what the person did, and how long they have been here. Everything else is yours.

## Adding your own fields

Anything you put in scope lands under app, and you can add whatever keys you like. Nothing about the library constrains their names.

```tsx
<JevProvider
  resolve={askJev}
  state={{
    app: { role: 'analyst', tier: 'enterprise', familiarity: 'returning' },
    recent_actions: [],
    time_spent: 'short',
  }}
>
```

Then name it from a question. State that nothing references is still sent, but the model has no idea what it is for until an ask points at it:

```tsx
<Gate ask="Given `app.tier` and `recent_actions`, is this person likely to need the advanced panel?" />
```

> Every channel travels with every question by default. Narrow it with `pick={[...]}` when a state grows big enough that irrelevant detail starts costing accuracy.

## Updating it

The state lives in the provider, so there is no store to wire up. `useJevState` reads it and gives you the three ways to change it.

```tsx
const { state, track, setAppField, setState } = useJevState();

track('exported CSV');                 // appends to recent_actions, capped
setAppField('tier', 'enterprise');     // one of your own fields
setState({ time_spent: 'long' });      // anything, merged in
```

Every judgment that receives the changed state re-resolves. That is affordable because what goes in is banded words, not raw telemetry.

## Observing every change

`onStateChange` fires after every change with the new state — not on the initial render. It is the general hook: persist it, sync it to a store you already have, log it. The library never decides what it means.

```tsx
<JevProvider
  resolve={askJev}
  state={{ app: { user } }}
  onStateChange={(next) => {
    sessionStorage.setItem(key, JSON.stringify({
      recent_actions: next.recent_actions,
      time_spent: next.time_spent,
    }));
  }}
>
```

> One handler, not a list — compose inside the arrow the way you would with any other React change handler. There is no built-in persistence yet: restoring on mount is yours to do, and doing it in an effect costs one extra judgment on first load because the first render sees the empty state.

## Reacting to your own store

The `state` prop is live, not just an initial value. Pass it from Redux, a session, or a server prop and the provider syncs each key whose value changes — compared structurally, so an inline object literal does not re-sync on every render, and a key you never change never disturbs what the library collected.

```tsx
const user = useSelector(selectUser);

<JevProvider resolve={askJev} state={{ app: { user } }}>
```

## Keeping time_spent current

`useTimeOnScreen()` maintains it while someone stays on a screen. It sets timers for the band boundaries rather than polling, so it wakes at most four times and then stops — anything finer would re-resolve every judgment on a ticking interval for no gain in what the model can tell.

```tsx
function ReportScreen() {
  useTimeOnScreen();   // time_spent: very short -> short -> medium -> long -> very long
  return <Branch ask="Given `time_spent`, does this person want the detailed view?" … />;
}
```

## Narrowing with pick

Accuracy degrades on a large state full of irrelevant detail, so a question can take less: `pick={["recent_actions"]}` sends only that channel plus its own data. The Inspector marks which fields went with the last request.

## Telemetry becomes words

Jev underperforms on numeric representations and does not count reliably, so raw telemetry is the wrong input. The library projects each signal onto a named band before it is ever sent.

| collected | sent |
| --- | --- |
| 41200 ms on the screen | time_spent: "long" |
| a click stream | recent_actions: ["filtered to EMEA", "exported CSV"] — the last 12 labels |
| 7 visits, in your own field | app.familiarity: "returns often" — via bucketFamiliarity |

Banding has a second benefit: it keeps re-resolution rare. Milliseconds churn on every tick, while "short" becomes "medium" a handful of times.

## When a judgment re-resolves

- Its question changed.
- Its data changed.
- Any state it receives changed — which is affordable because that state is banded words, not raw telemetry.
- You called revalidate() from the provider.

---

# Cost

> What a rendering decision costs, where the number comes from, and why batching is the whole argument.

Every component reports what its judgment cost. Jev bills per input token and output tokens are free, so the interesting figure is usually per thousand renders rather than per render.

```tsx
import { JevCost } from 'jev-ui';

const [cost, setCost] = useState<DecisionCost>();

<Branch ask="…" onResolved={setCost}>…</Branch>
<JevCost cost={cost} />        // this decision's share
<JevCost cost={cost} batch />  // the whole request
```

## What the numbers mean

| field | meaning |
| --- | --- |
| batchUsd | USD for the whole request this judgment travelled in. |
| shareUsd | batchUsd divided by the number of questions in that request. |
| decisions | How many questions shared the request. |
| requests | Upstream calls made. One for a whole render pass; zero on replay. |
| inputTokens | Tokens billed for the request. |
| estimated | True when the figure came from a recording rather than this call. |

> The share is an attribution, not a measurement. The API bills per request, so per-question cost cannot be observed — only divided. That division is the point: the marginal question is close to free.

## Why batching dominates the bill

A request ingests the state once and evaluates every question against it in parallel. Four judgments on one page are one request and one state ingestion, not four. Splitting them into separate calls multiplies the state, not just the questions.

## Overriding the rates

```tsx
createResolver({
  pricing: { 'jev-1.13.0': { inputPerMtokUsd: 0.042 } },
});
```

Published prices change and the built-in table will go stale. Treat the reported cost as an estimate you control, not as a bill.

---

# Transports and testing

> Run live, record fixtures, replay them offline, and prove the UI follows the judgment.

JEV_TRANSPORT decides how judgments are answered. The default is live when a key is present and replay when one is not, so a checkout with no key still runs.

| value | behaviour |
| --- | --- |
| live | One API call per batch. |
| record | Live, then writes one fixture per decision. |
| replay | Fixtures only. Throws on a miss rather than going live. |
| mock | Deterministic synthetic answers. No key, no network. |
| auto | Live, falling back to fixtures when the call fails. |

## Testing without spending anything

- Unit tests use the mock transport: no key, no network, fully deterministic.
- End-to-end tests run the app under replay, with the API key absent from that environment — the absence is what proves replay is really serving the judgments.
- A live contract test can be skipped when no key is present, so CI stays green either way.

## The test that actually matters

Edit a recorded answer on disk, reload, and assert the UI changed. Without that test, a component permanently rendering its fallback is indistinguishable from a working one.

```ts
// change the recorded choice from "line" to "stat"
record.answer = { type: 'choice', choice: 'stat', probabilities: { … }, confidence: 0.85 };
writeFileSync(fixturePath, JSON.stringify(record, null, 2));

await page.reload();
await expect(page.getByTestId('view-stat')).toBeVisible();
```