@chai-ui/react 0.1.0

package/DESIGN.md

@@ -0,0 +1,207 @@
+# CHAI UI — DESIGN.md
+
+The rules for building with `@chai-ui/react`, written for the people and
+the coding agents who integrate it. The API reference is the JSDoc on each
+component's props and the docs site's `llms.txt`. This file covers how to
+use the pieces correctly: which component to pick, which tokens to use,
+which states you get for free, and what not to build.
+
+If this file and the code disagree, the code wins. Please report the
+mismatch.
+
+## 1. Pick the component, don't rebuild it
+
+| You need | Use | Not |
+|---|---|---|
+| A prompt box with attach, model and aspect-ratio pickers, submit | `Composer` | A hand-built textarea + button row |
+| Media (image, video, audio) in, a generation-ready prompt out | `MediaAnalyzer` + `useMediaAnalyzer` | A file input plus your own model call |
+| One prompt's generated output (image, video, audio, text) | `ResultCard` | A custom media card |
+| Submit → engine → result state, wired together | `useComposer` | Your own fetch/loading/error state |
+| One reasoning model shared by every component | `ChaiProvider`, `useReasoning` | A text model picked per component |
+| A switch, an option menu, a pager | `Toggle`, `SearchMenu`, `Pagination` | Another UI kit's versions inside a CHAI surface |
+
+These don't exist yet. Don't import them, and don't invent stand-ins that
+use these names: `Results`, `Compare`, `ModelPicker`,
+`ParamControls`, `Presets`, `RunSummary`, `MediaViewer`, `createHttpEngine`.
+
+## 2. Integration rules
+
+1. **Load the CSS in order:** `@chai-ui/tokens/css` first, then
+   `@chai-ui/react/style.css`. Component styles read the token variables.
+2. **Everything is controlled.** Every value comes in as a prop and every
+   change comes out as a callback (`value` / `onChange`). Keep the state in
+   your app.
+3. **Advanced selection is the builder's opt-in.** `multiSelectModels`
+   and `multiSelectUseCases` are off by default. Turn them on only where
+   comparing models or making several media types at once is the point.
+4. **A callback's presence is the opt-in.** Omit `onEnhance` and there's
+   no optimize button. Omit `onAbort` and there's no stop button. Omit
+   `moreActions` and there's no ⋯ menu. Don't pass no-op handlers just to
+   make a control appear.
+5. **API keys never reach the browser.** Engines call one same-origin
+   route, `/api/chai/*`, served by `createChaiHandler` from
+   `@chai-ui/core/server`, which adds the key. Never pass a key to
+   `createFalEngine` or `createOpenRouterEngine`. In production, set the
+   handler's `authorize` and `allowedModels`.
+6. **Media generation and reasoning are separate choices.** `engine`
+   generates media and defaults to Fal.ai. `ChaiProvider`'s
+   reasoning models power Enhance, routing and text requests. Defaults:
+   Claude Opus 5 for text and images, Gemini 3.8 Flash for video and
+   audio, on OpenRouter. They're suggestions; respect a builder's own
+   `reasoningModel`, `reasoningModelByKind` and `reasoningEngine`.
+7. **Only show what's real.** Show cost only when the engine reports it.
+   Don't show model rankings or leaderboard positions you can't keep up to
+   date. Don't show a control the selected model can't honor.
+
+## 3. Material components, and where Chai uses its own
+
+Chai builds on Material Design 3's web components where they fit, and
+uses its own component where they don't. Both kinds take every color from
+Chai tokens (§4), so they look like one system.
+
+| Native Material component | Where Chai uses it |
+|---|---|
+| `<md-fab>` | The submit, retry and stop button |
+| `<md-switch>` (`Toggle`) | Auto-select model, and any switch you add |
+| `<md-checkbox>` | The checkboxes on rows in a multi-select model menu |
+| `<md-outlined-text-field>` | The search field in searchable menus |
+| `<md-focus-ring>` | The focus ring on all of the above |
+
+Chai's own components are the menus (`SearchMenu` and the attach menu),
+the use-case chips, `Pagination`, and the cards. The menus are the main
+difference, because Material has an `<md-menu>`:
+
+- **Placement.** `<md-menu>` opens as a floating popover anchored to a
+  corner of its trigger. Chai's menus open as a panel directly under their
+  trigger, inside the component, as the Figma designs show.
+- **Features `<md-menu>` doesn't have.** Chai's model menus need a search
+  field, grouped sections with headings (one per use case), a switch
+  pinned at the top (auto-select), and multi-select. `<md-menu>` closes
+  when an item is picked and has none of these.
+- **Portability.** Chai isn't tied to Material. Its own components restyle
+  entirely through tokens, which keeps the door open to other design
+  systems later.
+
+They still follow Material's conventions where they apply: a trailing
+check mark for single-select, MD3's own checkbox for multi-select,
+and Material's type scale. Each option is a plain button: reach it with
+Tab, pick it with Enter or Space; `aria-pressed` marks what's picked.
+
+## 4. Tokens
+
+All visual values come from `@chai-ui/tokens`, which builds from one JSON
+source into CSS variables, JS/TS and a Figma token set. **It is the only
+source of color:** no component contains a hard-coded color, and Material's
+colors are driven by Chai tokens, not the other way around.
+
+| Layer | Pattern | Use it for |
+|---|---|---|
+| Root palette | `--chai-color-root-{gray, green, amber, red}-*` | Nothing directly. It only feeds the layers below. `green-50` (`#009747`) is the brand green. |
+| Brand and state | `--chai-color-semantic-{accent, accent-hover, accent-subtle, accent-soft, accent-text, text-on-accent, warning, warning-subtle, danger, danger-subtle}` | The brand green and state colors. Use `accent` for fills, icons and focus rings, and `accent-text` for green text (`accent` is only 3.8:1 on white). |
+| Controls | `--chai-color-semantic-control-{surface, surface-hover, surface-raised, track, divider, border, border-soft, border-faint, text-strong, text, text-muted}` | The pure grays the components are built from. |
+| Overlays and media | `--chai-color-semantic-{overlay, on-overlay, scrim, media-backdrop}` | Buttons and backdrops on top of images and video |
+| Space | `--chai-space-0` … `--chai-space-8` (0, 4, 8, 12, 16, 24, 32, 48, 64px) | Padding, gaps, margins |
+| Radius | `--chai-radius-{sm, md, lg, full}` | Corners |
+| Type | `--chai-type-{family, size, weight, leading, tracking}-*` | Text |
+| Motion | `--chai-motion-duration-{fast, base, slow, steep}`, `--chai-motion-easing-{standard, growth}` | Transitions |
+| Effects | `--chai-shadow-menu`, `--chai-gradient-ai` | Floating menus, and the AI shimmer after prompt optimization |
+| Component | `--chai-composer-{bg, border, hover, placeholder, text}`, `--chai-media-analyzer-{bg, border, hover, text}` | Restyling that one component. Each defaults to a control role. |
+| Material | `--md-sys-color-*` | Nothing in your code. They exist so the Material switch, button and text field follow Chai tokens. |
+
+Rules:
+
+- **Never invent a token name.** If it isn't listed above or in
+  `@chai-ui/tokens/css`, it doesn't exist, and `var()` on an unknown name
+  silently falls back to nothing.
+- **Never put a literal color on a component.** Use a semantic role. If a
+  design needs a color that has no role yet, add the role to
+  `packages/tokens/src/tokens.json` instead of writing the hex.
+- **Restyle by overriding variables, not selectors.** Override the
+  semantic roles on `:root` to restyle everything, including the Material
+  components, or set a component variable like `--chai-composer-bg` on
+  `.chai-composer` to restyle one component. Don't target internal
+  `.chai-*__*` class names. Those are implementation details and can
+  change without notice.
+
+## 5. AI states you get for free — use them, don't replace them
+
+| Situation | Built-in behavior | Your part |
+|---|---|---|
+| Generation failed | `Composer`'s submit button becomes a retry action and an inline message appears (`submitError`) | Set `submitError`, and clear it on success or when the prompt changes. **No error dialogs or toasts for a failed generation.** |
+| Request in flight | Submit becomes a stop button (`submitting` + `onAbort`) | Pass `useComposer`'s `cancel` as `onAbort`; results show "Stopped" |
+| Prompt too thin | Optimize button rewrites the prompt, then offers undo (`onEnhance`) | Run the rewrite and call `onChange` with the new text |
+| No use case picked | The prompt is a text request and gets a text reply | Set `defaultUseCase` if your app's default should be image or video |
+| Result pending | `ResultCard` shows a spinner for `queued` / `running` | Nothing. `useComposer` sets the status. |
+| Long text answer | `ResultCard` keeps line breaks, scrolls past 400px with a visible scrollbar, and follows streaming text unless the person scrolls up | Change the height with `textMaxHeight` if needed |
+| Text streaming in | `ResultCard` renders partial text with a caret, marked `aria-busy` | Use an engine that calls `onText` (OpenRouter does, and so does the mock text engine). `useComposer` wires it. |
+| Result failed | `ResultCard` shows the error message in place | Nothing |
+| Try again | `ResultCard`'s retry fires `onAction("retry", result)` | Re-run the **same** model call, not a different one |
+| Feedback | Like/dislike fire `onAction`, and the displayed vote comes from `getVote` | Store votes yourself |
+| Details | The flip side shows prompt, model, tokens, cost and duration | Supply `models` so ids resolve to labels |
+| Quality checks | Each result's `evaluations` render on the flip side: green with a check if it passed, red with a cross if it failed | Run your checks in your backend proxy and add a top-level `evaluations: [{ id, label, passed }]` field to the JSON it returns (for a stream, send it as its own `data:` chunk). The built-in Fal and OpenRouter engines read that field, a custom engine returns it from `generate`, and `useComposer` puts it on the matching `Result`. CHAI never runs or scores anything itself, and there are no confidence scores. |
+
+`ResultCard` is where a run ends. Don't add a "use as input" action that
+feeds a result back into a `Composer`. Chaining steps like that is
+deliberately out of scope.
+
+## 6. Accessibility
+
+- Every icon-only button in CHAI has an accessible name. In `moreActions`,
+  `label` is the item's visible and announced text, so pass an `icon` that
+  is `aria-hidden`.
+- Animations (the optimize reveal, the streaming caret) are disabled under
+  `prefers-reduced-motion`. Your own motion around CHAI should do the same.
+- **Focus rings are on by default, as WCAG 2.2 AA requires** (2.4.7 Focus
+  Visible). Every control shows a ring when it
+  has keyboard focus: buttons and menu items use the browser's own ring,
+  MD3 elements use `<md-focus-ring>`, and the Composer rings its whole pill
+  while the prompt field is focused. Hover fills don't replace these,
+  because hover never appears for someone navigating with a keyboard.
+- **To hide them**, set `data-chai-focus-ring="hidden"` on any ancestor.
+  Every CHAI component inside it stops drawing focus rings, and your own
+  controls under the same ancestor are unaffected. Remove the attribute to
+  turn them back on:
+
+  ```tsx
+  <div data-chai-focus-ring={showFocusRings ? undefined : "hidden"}>…</div>
+  // or page-wide:
+  document.documentElement.dataset.chaiFocusRing = "hidden";
+  ```
+
+  **Hiding focus rings breaks WCAG 2.2 AA (and 2.1 AA) compliance.** Keyboard users
+  lose any indication of where they are. Only hide them on showcase or
+  preview surfaces, like the docs site's component previews, not in a
+  production app. Don't set `tabIndex={-1}` on CHAI controls either.
+- Streaming text is `aria-busy` until it settles, so screen readers read
+  the finished text once instead of every chunk.
+- **Supports WCAG 2.2 AA.** Chai's components are built to support WCAG 2.2 AA and are tested
+  against it with automated checks: axe (WCAG 2.0, 2.1 and 2.2, levels A
+  and AA) on every component state in the test suite, plus keyboard and
+  focus tests in a browser. They haven't been tested by hand with a
+  screen reader, so this is support, not a certification. Compliance is
+  judged for a whole app, so test yours, including with a screen reader.
+
+  What that covers: contrast, focus rings, a name for every control
+  (`Composer`'s `promptLabel`, `Toggle`'s `ariaLabel`), alt text for
+  generated images (`ResultCard`'s `altText`, default the prompt), 24px
+  targets, and keyboard use: video play/pause (Tab to the video, Space)
+  and seeking (a slider: arrow keys, Home, End), the turned-away side of a
+  flipped card is `inert` and focus follows the flip, and the expanded
+  view is a dialog (focus inside, Escape closes, focus returns to Expand).
+
+## 7. What's enforced
+
+Inside this repo, `pnpm lint` runs `scripts/lint-tokens.mjs` over the
+packages' CSS:
+
+- It fails on `var(--…)` names that don't exist (invented tokens).
+- It fails on any hard-coded color, custom properties included.
+- It fails on direct use of Material's `--md-sys-color-*` roles, which
+  must go through the Chai token they map to.
+
+TypeScript enforces the component APIs: controlled props, typed submit
+payloads, and typed engine and result shapes. `ResultCard`'s `onAction`
+is a plain `string` so it can carry your own `moreActions` ids, which
+means a misspelled action name isn't caught. Nothing checks your
+app's own CSS or markup yet, so sections 1–6 above are guidance there, not
+guarantees.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kazarazat
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,265 @@
+# @chai-ui/react
+
+React components for the input and output surfaces of generative-media
+apps. Everything here is controlled — you own the state, these components
+render it and tell you when it changes.
+
+Building with it, or pointing a coding agent at it? Read
+[`DESIGN.md`](./DESIGN.md) (shipped in the package) for the usage rules:
+which component to pick, which tokens exist, the built-in AI states, and
+what not to build.
+
+Chai's components support WCAG 2.2 AA: tested with axe and automated
+keyboard and focus checks, not by hand with a screen reader. DESIGN.md §6
+has the details. Focus rings are visible by default, as WCAG requires.
+`data-chai-focus-ring="hidden"` on an ancestor hides them, for preview or
+showcase surfaces only. `Composer`'s `promptLabel` names the prompt field
+(default: the placeholder), and `ResultCard`'s `altText` sets image alt
+text (default: the prompt).
+
+## Quick start: `Composer`
+
+`Composer` is the `bar`-layout input surface: a prompt field, an attach
+menu, a use-case chip, model/aspect-ratio pickers, and submit — all driven
+by which props you supply, not by four separate components.
+
+```tsx
+import { useState } from "react";
+import "@chai-ui/tokens/css";
+import "@chai-ui/react/style.css";
+import { Composer, type ComposerAttachment, type ComposerSubmitPayload } from "@chai-ui/react";
+
+function App() {
+  const [value, setValue] = useState("");
+  const [attachments, setAttachments] = useState<ComposerAttachment[]>([]);
+
+  function handleSubmit(payload: ComposerSubmitPayload) {
+    // payload = { value, attachments, useCase, modelId, aspectRatio } —
+    // everything Composer tracks, assembled for you. Send it to whichever
+    // model/provider you've set up; Composer never calls one itself.
+    console.log(payload);
+  }
+
+  return (
+    <Composer
+      value={value}
+      onChange={setValue}
+      attachments={attachments}
+      onAttachmentsChange={setAttachments}
+      onSubmit={handleSubmit}
+    />
+  );
+}
+```
+
+That's the minimal case — no model picker, no aspect ratio, no attach
+capability beyond the default file picker. Every other control is additive:
+
+```tsx
+<Composer
+  value={value}
+  onChange={setValue}
+  attachments={attachments}
+  onAttachmentsChange={setAttachments}
+  // A use-case chip + model/aspect-ratio pickers only appear once `useCase`
+  // is set — wire it from the attach menu's own picks, or set it yourself.
+  useCase={useCase}
+  onClearUseCase={() => setUseCase(null)}
+  onAttachMenuSelect={(action) => {
+    if (action === "create-image") setUseCase({ kind: "image", label: "Image" });
+  }}
+  models={models}
+  modelId={modelId}
+  onModelChange={setModelId}
+  // An "Auto-select model" switch appears at the top of the model menu so
+  // the end user can flip it — omit `showAutoSelectToggle` to keep it a
+  // fixed, builder-only setting with no visible control instead.
+  autoSelectModel={autoSelectModel}
+  showAutoSelectToggle
+  onAutoSelectModelChange={setAutoSelectModel}
+  aspectRatios={aspectRatios}
+  aspectRatio={aspectRatio}
+  onAspectRatioChange={setAspectRatio}
+  // Omit onEnhance entirely to hide the "optimize prompt" button — e.g.
+  // before you've wired an engine that can actually run the rewrite.
+  onEnhance={(currentValue) => runEnhance(currentValue).then(setValue)}
+  onSubmit={handleSubmit}
+/>
+```
+
+The full prop list — including `attachments`' file-reading behavior,
+`onUnsupportedFile`, and `disabled`/`submitDisabled` — is documented as
+JSDoc directly on `ComposerProps` in `src/Composer.tsx`; every prop and
+event follows the same `value`/`onChange` shape used everywhere else in
+this package.
+
+See the [Composer page on the docs site](https://chai-ui.com/docs/components/composer-bar)
+for a live example with every opt-in feature.
+
+### No use case picked: a text request
+
+A prompt typed with no use case picked is a text request
+(`TEXT_USE_CASE`): it gets a text reply rather than doing nothing. For an
+app that's mostly about images, set the default instead; it's never shown
+as a chip:
+
+```tsx
+<Composer defaultUseCase={{ kind: "image", label: "Image" }} … />
+```
+
+### Several models, several use cases (builder opt-ins, off by default)
+
+```tsx
+// Several models: each produces its own result, paged inside one ResultCard.
+<Composer multiSelectModels modelIds={modelIds} onModelIdsChange={setModelIds} models={models} … />
+
+// Several use cases at once (at most one per kind): the Model menu shows a
+// section per picked use case, and onSubmit gets one selection per use case.
+<Composer
+  multiSelectUseCases
+  useCases={useCases}
+  onUseCasesChange={setUseCases}
+  modelsByKind={{ image: imageModels, video: videoModels }}
+  modelIds={modelIds}
+  onModelIdsChange={setModelIds}
+  …
+/>
+```
+
+Either way `onSubmit` receives `selections`: one `{ useCase, modelIds, models }`
+entry per use case.
+
+With `autoSelectModel` on, the trigger reads "Auto-select" and
+`useComposer` picks the model at submit: the reasoning model reads the
+prompt and media and chooses from that use case's `models`. Pass
+`onModelChange` (or `onModelIdsChange`) to the hook too, so the trigger
+shows the pick:
+
+```tsx
+const { submit, routing } = useComposer({ engine, onModelChange: setModelId });
+```
+
+If routing can't run (no `ChaiProvider`, a failed reasoning call, an
+unlisted reply), the request runs on the first listed model and
+`onRoutingFallback` says why.
+
+## What else this package ships
+
+- **`MediaAnalyzer`** — drop in an image, video, or audio clip and get a
+  generation-ready prompt back, with kind-aware model menus and a prompt
+  length picker. Wire it with `useMediaAnalyzer()`, which sends the media
+  to `ChaiProvider`'s reasoning model and returns the prompt:
+  `onSubmit={submit} submitting={analyzing} submitError={error}`.
+- **`ResultCard`** — renders one prompt's generated results (image, video,
+  audio, or text) with like/dislike/retry/download/share, a configurable
+  "more" menu, pagination across multiple results, and an info flip showing
+  the prompt and model metadata. Live example:
+  [chai-ui.com/docs/components/result-card](https://chai-ui.com/docs/components/result-card).
+- **Primitives** (`src/primitives/`) — `Toggle` (an MD3 switch),
+  `SearchMenu` (the model/option menu behind every picker — Chai's own rather than Material's `<md-menu>`; DESIGN.md §3 says why), and
+  `Pagination` (a progress-style pager any paginated surface can reuse).
+  The components are built from these; they're also exported directly if
+  you're assembling your own layout.
+
+## `useComposer` — wiring `Composer` to a real engine
+
+```tsx
+import { ChaiProvider, useComposer, createFalEngine, Composer, ResultCard } from "@chai-ui/react";
+
+// The reasoning models write text (Enhance, routing, text requests) and
+// are separate from the media engine. With no props,
+// Claude Opus 5 handles text and images, Gemini 3.8 Flash handles video
+// and audio, both on `createOpenRouterEngine()`. Without a provider,
+// Composer's Enhance button stays hidden.
+function Root() {
+  return (
+    <ChaiProvider>
+      <App />
+    </ChaiProvider>
+  );
+}
+
+function App() {
+  const { run, submit, cancel, enhance, enhancing } = useComposer({
+    engine: createFalEngine({ outputKind: "image" }),
+  });
+  const busy = run?.results.some((r) => r.status === "queued" || r.status === "running") ?? false;
+
+  return (
+    <>
+      <Composer
+        value={value}
+        onChange={setValue}
+        onSubmit={submit}
+        submitting={busy}
+        onAbort={cancel}
+        onEnhance={enhance ? (v) => enhance(v).then(setValue) : undefined}
+        enhancing={enhancing}
+        // ...the rest of Composer's own props, as above
+      />
+      {run && (
+        <ResultCard
+          results={run.results}
+          prompt={run.request.prompt}
+          onAction={(action, result) => {
+            // like / dislike / retry / download / share / your "more" actions
+          }}
+        />
+      )}
+    </>
+  );
+}
+```
+
+`submit` takes `Composer`'s `ComposerSubmitPayload` directly — pass it
+straight to `onSubmit`. It turns each selection into a real the design
+`Request`/`Run`/`Result`: creates a `"queued"` `Result` per model up
+front, then folds each one to `"running"` → `"done"`/`"error"` as the
+engine settles it. `run` is the first `Run` (or `null` before the first
+submit); `runs` holds one per use case when `multiSelectUseCases` is on.
+`ResultCard` renders `run.results` directly, paginating when there's more
+than one.
+
+**The server route.** `createFalEngine()` and the OpenRouter reasoning
+engine call `/api/chai/*` on your server, which adds the API keys. Add it
+with one file, then set `FAL_KEY` and `OPENROUTER_API_KEY`:
+
+```ts
+// Next.js: app/api/chai/[...path]/route.ts
+import { createChaiHandler } from "@chai-ui/core/server";
+export const { GET, POST, PUT } = createChaiHandler();
+```
+
+Other frameworks, and the `authorize` / `allowedModels` settings to add
+before going live, are in the `@chai-ui/core` README.
+
+Every default is a suggestion. Swap any of them:
+
+```tsx
+<ChaiProvider
+  reasoningModel="your/text-and-image-model"
+  // Cheaper video and audio analysis; kinds you leave out keep their default.
+  reasoningModelByKind={{ video: "qwen/qwen3.8-omni-flash", audio: "qwen/qwen3.8-omni-flash" }}
+  reasoningEngine={yourEngine}
+/>
+```
+
+The defaults are exported as `DEFAULT_REASONING_MODEL` and
+`DEFAULT_REASONING_MODEL_BY_KIND`.
+
+`useComposer`'s own `reasoningEngine` + `reasoningModel` override the
+provider's, but only when both are set. Text requests go to `textEngine`
+(default: the reasoning engine, then a mock text engine), using
+`textModel` (default: the reasoning model) when no model is picked. Other kinds go to `engineByKind[kind]`, then `engine`. With no
+model picked, the engine's own default model runs.
+
+**Stop.** `cancel()` stops the current submit: wire it to Composer's
+`onAbort`, with `submitting` true while results are queued or running.
+Unfinished results turn `"cancelled"` (ResultCard shows "Stopped"; a
+streamed text result keeps what arrived), and a new submit cancels the
+previous one. Cancellation is best effort at the provider: Fal removes a
+queued request and signals a running one, which may still finish;
+OpenRouter stops a *streaming* request, and its billing, only for
+providers that support it (not Google); a non-streaming request keeps
+running. A custom engine receives `signal` in `generate()`: cancel at the
+provider if it can, then reject with an `AbortError` (`abortError()`).

package/dist/ChaiProvider.d.ts

@@ -0,0 +1,49 @@
+import { type ReactNode } from "react";
+import { type DroppedMedia, type GenerationEngine, type MediaKind } from "@chai-ui/core";
+/**
+ * The suggested reasoning model for text and images: prompt enhancement,
+ * auto-select routing and image analysis. A default, not a requirement —
+ * pass any model id `reasoningEngine` can run.
+ */
+export declare const DEFAULT_REASONING_MODEL = "anthropic/claude-opus-5";
+/**
+ * Suggested per-kind overrides for media Claude can't read. Gemini takes
+ * video and audio directly. For a cheaper option, swap in
+ * `"qwen/qwen3.8-omni-flash"`, which takes both too.
+ */
+export declare const DEFAULT_REASONING_MODEL_BY_KIND: Partial<Record<MediaKind, string>>;
+/** The reasoning engine and models every CHAI component shares. */
+export interface Reasoning {
+    engine: GenerationEngine;
+    /** The model for text and any attachment kind without its own entry in `modelByKind`. */
+    model: string;
+    modelByKind: Partial<Record<MediaKind, string>>;
+}
+export interface ChaiProviderProps {
+    /** Text, image and routing model. Defaults to `DEFAULT_REASONING_MODEL`. */
+    reasoningModel?: string;
+    /**
+     * Per-attachment-kind models, merged over `DEFAULT_REASONING_MODEL_BY_KIND`
+     * one kind at a time, e.g. `{ video: "qwen/qwen3.8-omni-flash" }` keeps
+     * the default for audio. Map a kind to `reasoningModel`'s value to use
+     * one model for everything.
+     */
+    reasoningModelByKind?: Partial<Record<MediaKind, string>>;
+    /**
+     * The engine the reasoning models run on. Defaults to OpenRouter,
+     * independent of the generation engine: Fal's own LLM access is an
+     * OpenRouter proxy, so defaulting to it would double-proxy.
+     */
+    reasoningEngine?: GenerationEngine;
+    children?: ReactNode;
+}
+export declare function ChaiProvider({ reasoningModel, reasoningModelByKind, reasoningEngine, children }: ChaiProviderProps): import("react").JSX.Element;
+/** The nearest `ChaiProvider`'s reasoning engine and models, or `undefined` outside one. */
+export declare function useReasoning(): Reasoning | undefined;
+/**
+ * The reasoning model for a call with these attachments: the first
+ * attachment whose kind has its own model wins (a clip plus a still goes
+ * to the model that can read the clip), else `reasoning.model`.
+ */
+export declare function reasoningModelFor(reasoning: Reasoning, attachments?: DroppedMedia[]): string;
+//# sourceMappingURL=ChaiProvider.d.ts.map

package/dist/ChaiProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ChaiProvider.d.ts","sourceRoot":"","sources":["../src/ChaiProvider.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAsC,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAC3E,OAAO,EAA0B,KAAK,YAAY,EAAE,KAAK,gBAAgB,EAAE,KAAK,SAAS,EAAE,MAAM,eAAe,CAAC;AAEjH;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,4BAA4B,CAAC;AAEjE;;;;GAIG;AACH,eAAO,MAAM,+BAA+B,EAAE,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,CAG9E,CAAC;AAEF,mEAAmE;AACnE,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,gBAAgB,CAAC;IACzB,yFAAyF;IACzF,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC,CAAC;CACjD;AAID,MAAM,WAAW,iBAAiB;IAChC,4EAA4E;IAC5E,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;OAKG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC,CAAC;IAC1D;;;;OAIG;IACH,eAAe,CAAC,EAAE,gBAAgB,CAAC;IACnC,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AAED,wBAAgB,YAAY,CAAC,EAAE,cAAc,EAAE,oBAAoB,EAAE,eAAe,EAAE,QAAQ,EAAE,EAAE,iBAAiB,+BAgBlH;AAMD,4FAA4F;AAC5F,wBAAgB,YAAY,IAAI,SAAS,GAAG,SAAS,CAEpD;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,SAAS,EAAE,WAAW,GAAE,YAAY,EAAO,GAAG,MAAM,CAMhG"}

package/dist/ChaiProvider.js

@@ -0,0 +1,54 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext, useMemo } from "react";
+import { createOpenRouterEngine } from "@chai-ui/core";
+/**
+ * The suggested reasoning model for text and images: prompt enhancement,
+ * auto-select routing and image analysis. A default, not a requirement —
+ * pass any model id `reasoningEngine` can run.
+ */
+export const DEFAULT_REASONING_MODEL = "anthropic/claude-opus-5";
+/**
+ * Suggested per-kind overrides for media Claude can't read. Gemini takes
+ * video and audio directly. For a cheaper option, swap in
+ * `"qwen/qwen3.8-omni-flash"`, which takes both too.
+ */
+export const DEFAULT_REASONING_MODEL_BY_KIND = {
+    video: "google/gemini-3.8-flash",
+    audio: "google/gemini-3.8-flash",
+};
+const ReasoningContext = createContext(undefined);
+export function ChaiProvider({ reasoningModel, reasoningModelByKind, reasoningEngine, children }) {
+    const engine = useMemo(() => reasoningEngine ?? createOpenRouterEngine(), [reasoningEngine]);
+    const model = reasoningModel ?? DEFAULT_REASONING_MODEL;
+    const video = reasoningModelByKind?.video;
+    const audio = reasoningModelByKind?.audio;
+    const image = reasoningModelByKind?.image;
+    const text = reasoningModelByKind?.text;
+    const value = useMemo(() => ({
+        engine,
+        model,
+        modelByKind: { ...DEFAULT_REASONING_MODEL_BY_KIND, ...dropUndefined({ video, audio, image, text }) },
+    }), [engine, model, video, audio, image, text]);
+    return _jsx(ReasoningContext.Provider, { value: value, children: children });
+}
+function dropUndefined(obj) {
+    return Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== undefined));
+}
+/** The nearest `ChaiProvider`'s reasoning engine and models, or `undefined` outside one. */
+export function useReasoning() {
+    return useContext(ReasoningContext);
+}
+/**
+ * The reasoning model for a call with these attachments: the first
+ * attachment whose kind has its own model wins (a clip plus a still goes
+ * to the model that can read the clip), else `reasoning.model`.
+ */
+export function reasoningModelFor(reasoning, attachments = []) {
+    for (const { kind } of attachments) {
+        const model = reasoning.modelByKind[kind];
+        if (model)
+            return model;
+    }
+    return reasoning.model;
+}
+//# sourceMappingURL=ChaiProvider.js.map

package/dist/ChaiProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ChaiProvider.js","sourceRoot":"","sources":["../src/ChaiProvider.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,OAAO,EAAkB,MAAM,OAAO,CAAC;AAC3E,OAAO,EAAE,sBAAsB,EAA4D,MAAM,eAAe,CAAC;AAEjH;;;;GAIG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,yBAAyB,CAAC;AAEjE;;;;GAIG;AACH,MAAM,CAAC,MAAM,+BAA+B,GAAuC;IACjF,KAAK,EAAE,yBAAyB;IAChC,KAAK,EAAE,yBAAyB;CACjC,CAAC;AAUF,MAAM,gBAAgB,GAAG,aAAa,CAAwB,SAAS,CAAC,CAAC;AAqBzE,MAAM,UAAU,YAAY,CAAC,EAAE,cAAc,EAAE,oBAAoB,EAAE,eAAe,EAAE,QAAQ,EAAqB;IACjH,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC,eAAe,IAAI,sBAAsB,EAAE,EAAE,CAAC,eAAe,CAAC,CAAC,CAAC;IAC7F,MAAM,KAAK,GAAG,cAAc,IAAI,uBAAuB,CAAC;IACxD,MAAM,KAAK,GAAG,oBAAoB,EAAE,KAAK,CAAC;IAC1C,MAAM,KAAK,GAAG,oBAAoB,EAAE,KAAK,CAAC;IAC1C,MAAM,KAAK,GAAG,oBAAoB,EAAE,KAAK,CAAC;IAC1C,MAAM,IAAI,GAAG,oBAAoB,EAAE,IAAI,CAAC;IACxC,MAAM,KAAK,GAAG,OAAO,CACnB,GAAG,EAAE,CAAC,CAAC;QACL,MAAM;QACN,KAAK;QACL,WAAW,EAAE,EAAE,GAAG,+BAA+B,EAAE,GAAG,aAAa,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,EAAE;KACrG,CAAC,EACF,CAAC,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,CAAC,CAC3C,CAAC;IACF,OAAO,KAAC,gBAAgB,CAAC,QAAQ,IAAC,KAAK,EAAE,KAAK,YAAG,QAAQ,GAA6B,CAAC;AACzF,CAAC;AAED,SAAS,aAAa,CAAmB,GAAM;IAC7C,OAAO,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,SAAS,CAAC,CAAe,CAAC;AAClG,CAAC;AAED,4FAA4F;AAC5F,MAAM,UAAU,YAAY;IAC1B,OAAO,UAAU,CAAC,gBAAgB,CAAC,CAAC;AACtC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,SAAoB,EAAE,cAA8B,EAAE;IACtF,KAAK,MAAM,EAAE,IAAI,EAAE,IAAI,WAAW,EAAE,CAAC;QACnC,MAAM,KAAK,GAAG,SAAS,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;QAC1C,IAAI,KAAK;YAAE,OAAO,KAAK,CAAC;IAC1B,CAAC;IACD,OAAO,SAAS,CAAC,KAAK,CAAC;AACzB,CAAC"}