@chai-ui/core 0.10.1 → 0.11.0

package/src/composer.ts

@@ -29,7 +29,7 @@ import {
   type Run,
 } from "./run.js";
 import type { ComposerPromptField } from "./composer-view.js";
-import type { DroppedMedia, GenerationUseCase, MediaKind, ModelOption, OutputKind } from "./types.js";
+import type { AudioUseCase, DroppedMedia, GenerationUseCase, MediaKind, ModelOption, OutputKind } from "./types.js";
 
 export interface ComposerAttachment extends DroppedMedia {
   id: string;
@@ -52,6 +52,8 @@ export interface ComposerUseCase {
    * either a prompt or a region. Images only for now.
    */
   edit?: boolean;
+  /** For an `"audio"` use case, which audio it creates: spoken words or music. */
+  audio?: AudioUseCase;
 }
 
 /** A plain text request — what a submit means when no use case is picked, unless the builder sets `defaultUseCase`. */
@@ -60,6 +62,12 @@ export const TEXT_USE_CASE: ComposerUseCase = { kind: "text", label: "Text" };
 /** Editing the attached image, the attach menu's "Edit image". Pair it with `useComposer`'s `editImage` and an `EditCard`. */
 export const EDIT_IMAGE_USE_CASE: ComposerUseCase = { kind: "image", label: "Edit image", edit: true };
 
+/** Spoken audio from text, the attach menu's "Create speech". */
+export const CREATE_SPEECH_USE_CASE: ComposerUseCase = { kind: "audio", label: "Speech", audio: "speech" };
+
+/** Music from a description, the attach menu's "Create music". */
+export const CREATE_MUSIC_USE_CASE: ComposerUseCase = { kind: "audio", label: "Music", audio: "music" };
+
 /** One use case to run and the models picked for it. Empty `modelIds` means the engine's default model. */
 export interface ComposerSelection {
   useCase: ComposerUseCase;
@@ -92,6 +100,15 @@ export interface ComposerSubmitPayload {
   character?: string;
   /** The picked frame rate for a world, or null for the model's default. Undefined for other use cases. */
   frameRate?: number | null;
+  /** The picked voice for Create speech, or null for the model's default. Undefined for other use cases. */
+  speechVoice?: string | null;
+  /** The picked genres for Create music, written into the prompt at submit. Undefined for other use cases. */
+  genres?: string[];
+}
+
+/** A music prompt with the picked genres written in: music models take genre as part of the description. */
+export function promptWithGenres(prompt: string, genres: string[]): string {
+  return genres.length > 0 ? `${prompt.trim()}\n\nGenre: ${genres.join(", ")}` : prompt;
 }
 
 /**
@@ -212,7 +229,13 @@ function defaultEnhancePrompt(value: string, mode?: GenerationUseCase, field: Co
   if (field === "character") {
     return `Rewrite the following description of the character a person plays in an interactive world to be more detailed and specific, keeping the same intent: who or what they are, how they look, and how they move. Don't describe the world around them. ${reply}\n\n${value}`;
   }
-  const subject = mode?.includes("video")
+  // The prompt is the script itself: keep the words, only make them read aloud well.
+  if (mode === "text-to-speech") {
+    return `Edit the following text so it reads naturally when spoken aloud: fix punctuation, and spell out numbers, symbols and abbreviations. Keep the same words and meaning. Reply with only the edited text, nothing else.\n\n${value}`;
+  }
+  const subject = mode === "text-to-music"
+    ? "a music-generation"
+    : mode?.includes("video")
     ? "a video-generation"
     : mode === "text-to-text" || mode === "vision"
       ? "an AI assistant"
@@ -314,9 +337,10 @@ export function createComposerStore(getOptions: () => ComposerOptions, getProvid
       if (payload.character?.trim()) params.character = payload.character;
       if (payload.frameRate != null) params.frameRate = payload.frameRate;
     }
+    if (selection.useCase.audio === "speech" && payload.speechVoice) params.voice = payload.speechVoice;
     const request: Request = {
       mode: deriveGenerationUseCase(selection.useCase, attachments),
-      prompt: payload.value,
+      prompt: selection.useCase.audio === "music" ? promptWithGenres(payload.value, payload.genres ?? []) : payload.value,
       attachments,
       modelIds: selection.modelIds.length > 0 ? selection.modelIds : [fallback ?? DEFAULT_MODEL_ID],
       params,
@@ -382,6 +406,7 @@ export function createComposerStore(getOptions: () => ComposerOptions, getProvid
             aspectRatio: newRun.request.params.aspectRatio as string | undefined,
             character: newRun.request.params.character as string | undefined,
             frameRate: newRun.request.params.frameRate as number | undefined,
+            voice: newRun.request.params.voice as string | undefined,
             // Text engines that stream fill `output` in while still "running".
             onText: (text) => update(newRun.id, (r) => streamResult(r, result.id, text)),
             signal,

package/src/engine.ts

@@ -27,6 +27,8 @@ export interface GenerationEngine {
     character?: string;
     /** A world's frame rate, e.g. `16`. Only set for a model that lists it in `ModelOption.frameRates`. */
     frameRate?: number;
+    /** A text-to-speech voice, the model's own id for it. Only set for a model that lists it in `ModelOption.voices`. */
+    voice?: string;
     /**
      * Optional streaming hook for text output. An engine that can stream
      * calls this with the full text received so far (not a delta) each time

package/src/engines/fal.ts

@@ -22,7 +22,7 @@
  */
 
 import { abortError, abortableSleep, isAbortError, readEvaluations, type GenerationEngine } from "../engine.js";
-import type { DroppedMedia, MediaKind } from "../types.js";
+import type { DroppedMedia, FalInputFormat, MediaKind, ModelOption } from "../types.js";
 import { SUGGESTED_FAL_MODELS } from "../suggested-models.js";
 import type { Transcribe } from "../voice-input.js";
 
@@ -38,6 +38,12 @@ export interface FalEngineOptions {
   modelByKind?: Partial<Record<FalOutputKind, string>>;
   /** Which kind of media this engine instance produces. Defaults to "image". */
   outputKind?: FalOutputKind;
+  /**
+   * Your own models, so the engine sends each one's inputs in the fields its
+   * Fal schema names (`ModelOption.falInput`). Chai's suggested models are
+   * already known.
+   */
+  models?: ModelOption[];
   /** Poll interval while a queued job is in progress. Defaults to 1500ms. */
   pollIntervalMs?: number;
   /** Give up waiting after this long. Defaults to 120000ms (2 min) — video/audio jobs run longer than image ones. */
@@ -48,9 +54,9 @@ export interface FalEngineOptions {
 
 /**
  * Fal model ids verified live against fal.ai's own docs/catalog
- * 2026-09-24, not invented. No default for "audio": CHAI has no audio
- * `GenerationUseCase` yet, so guessing one
- * here would be ahead of any real use case that needs it.
+ * 2026-09-24, not invented. No default for "audio": Create speech and
+ * Create music are opt-in, so the builder names the model when they turn
+ * one on.
  */
 const DEFAULT_MODEL_BY_KIND: Partial<Record<FalOutputKind, string>> = {
   image: "fal-ai/flux/schnell",
@@ -132,9 +138,13 @@ export function buildFalRequestBody(args: {
   attachments?: DroppedMedia[];
   model?: string;
   aspectRatio?: string;
+  voice?: string;
+  /** The model's input format when the caller knows it (see `FalEngineOptions.models`); else a suggested model's, else guessed. */
+  input?: FalInputFormat;
 }): Record<string, unknown> {
-  const body: Record<string, unknown> = { prompt: args.prompt };
-  const known = args.model ? SUGGESTED_FAL_MODELS.get(args.model)?.falInput : undefined;
+  const known = args.input ?? (args.model ? SUGGESTED_FAL_MODELS.get(args.model)?.falInput : undefined);
+  const body: Record<string, unknown> = { [known?.prompt ?? "prompt"]: args.prompt };
+  if (args.voice) body.voice = args.voice;
   if (args.aspectRatio) {
     const sizes = args.model?.startsWith("fal-ai/gpt-image")
       ? GPT_IMAGE_1_SIZES
@@ -241,7 +251,7 @@ export function createFalEngine(options: FalEngineOptions = {}): GenerationEngin
   const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
 
   return {
-    async generate({ modelId, prompt, attachments, aspectRatio, signal }) {
+    async generate({ modelId, prompt, attachments, aspectRatio, voice, signal }) {
       const model =
         modelId ?? options.modelByKind?.[outputKind] ?? options.model ?? DEFAULT_MODEL_BY_KIND[outputKind];
       if (!model) {
@@ -250,7 +260,8 @@ export function createFalEngine(options: FalEngineOptions = {}): GenerationEngin
         );
       }
 
-      const body = buildFalRequestBody({ prompt, attachments, model, aspectRatio });
+      const input = options.models?.find((m) => m.id === model)?.falInput;
+      const body = buildFalRequestBody({ prompt, attachments, model, aspectRatio, voice, input });
       if (signal?.aborted) throw abortError();
 
       try {

package/src/index.ts

@@ -17,3 +17,4 @@ export * from "./result-format.js";
 export * from "./composer-view.js";
 export * from "./edit-card.js";
 export * from "./voice-input.js";
+export * from "./menu-placement.js";

package/src/menu-placement.ts

@@ -0,0 +1,29 @@
+/**
+ * Which way a component's menus open from their trigger. `"above"` suits a
+ * bar docked to the bottom of the screen and `"below"` one docked to the
+ * top; `"auto"` measures at open time, for a bar that sits in the page.
+ */
+export type MenuPlacement = "auto" | "above" | "below";
+
+/** The gap between a trigger and its open menu, and the least room kept to the screen's edge. */
+const GAP = 8;
+const EDGE = 16;
+
+/**
+ * Whether a menu opens above its trigger. `"auto"` opens below when the menu
+ * fits there, above when only that side fits, and otherwise toward the side
+ * with more room, so it's never cut off when it could have fit.
+ */
+export function menuOpensAbove(
+  placement: MenuPlacement,
+  trigger: { top: number; bottom: number },
+  menuHeight: number,
+  viewportHeight: number
+): boolean {
+  if (placement !== "auto") return placement === "above";
+  const roomBelow = viewportHeight - EDGE - (trigger.bottom + GAP);
+  const roomAbove = trigger.top - GAP - EDGE;
+  if (menuHeight <= roomBelow) return false;
+  if (menuHeight <= roomAbove) return true;
+  return roomAbove > roomBelow;
+}

package/src/run.ts

@@ -4,7 +4,7 @@
  * (`@chai-ui/react`) is the thin React binding on top.
  */
 
-import type { DroppedMedia, Evaluation, GenerationUseCase, MediaKind, OutputKind, Usage } from "./types.js";
+import type { AudioUseCase, DroppedMedia, Evaluation, GenerationUseCase, MediaKind, OutputKind, Usage } from "./types.js";
 
 export interface Request {
   /** The specific generation use case, when one could be derived — see `deriveGenerationUseCase`. Undefined when the use case (or its kind) has no `GenerationUseCase` match yet, e.g. audio. */
@@ -134,16 +134,20 @@ export function cancelResult(run: Run, resultId: string): Run {
  * Derives a `GenerationUseCase` from Composer's own `{ kind, label }` use
  * case plus whether anything is attached — this is real derivation logic,
  * not just plumbing: the same `kind: "video"` means `"text-to-video"` with
- * nothing attached but `"image-to-video"` once an image is. Returns
- * `undefined` for "audio" and "world" (no `GenerationUseCase` member exists
- * yet; audio generation is planned, world models await provider specs). `"text"` is a text request: a reply to
+ * nothing attached but `"image-to-video"` once an image is. An `"audio"`
+ * use case is `"text-to-speech"` or `"text-to-music"` by its `audio` field,
+ * and `undefined` without one. Returns `undefined` for "world" (world
+ * models await provider specs). `"text"` is a text request: a reply to
  * the prompt, or a description of the attached media ("vision").
  */
 export function deriveGenerationUseCase(
-  useCase: { kind: OutputKind } | null | undefined,
+  useCase: { kind: OutputKind; audio?: AudioUseCase } | null | undefined,
   attachments: DroppedMedia[]
 ): GenerationUseCase | undefined {
   if (!useCase) return undefined;
+  if (useCase.kind === "audio") {
+    return useCase.audio === "speech" ? "text-to-speech" : useCase.audio === "music" ? "text-to-music" : undefined;
+  }
   const hasMedia = attachments.length > 0;
   if (useCase.kind === "video") return hasMedia ? "image-to-video" : "text-to-video";
   if (useCase.kind === "image") return hasMedia ? "image-edit" : "text-to-image";

package/src/types.ts

@@ -12,6 +12,13 @@ export type MediaKind = "image" | "video" | "audio" | "text";
  */
 export type OutputKind = MediaKind | "world";
 
+/**
+ * Which audio an `"audio"` use case creates: spoken words (Create speech) or
+ * music (Create music). Each needs its own models and result surface, so a
+ * new kind of audio (e.g. sound effects) gets its own value, not a reuse.
+ */
+export type AudioUseCase = "speech" | "music";
+
 /**
  * A piece of media a person attached (or an engine received) — just enough
  * to know its kind and where it lives.
@@ -119,12 +126,33 @@ export interface ModelOption {
    * a model with one fixed rate it doesn't take as an input: no menu shows.
    */
   frameRates?: number[];
+  /**
+   * The voices a text-to-speech model speaks in, from its schema. Composer's
+   * Voice menu offers them once this is the one model picked, and the
+   * engine sends the pick as the model's `voice` input. Leave it out for a
+   * model with no voice to choose.
+   */
+  voices?: VoiceOption[];
+  /**
+   * The genres offered with a music model. Composer's Genre menu offers the
+   * ones every picked model lists, several at once. Music models take genre
+   * as part of the description, so the picks are written into the prompt
+   * (see `promptWithGenres`).
+   */
+  genres?: ParameterOption<string>[];
+}
+
+/** One voice in `ModelOption.voices`: the model's own id for it, its name, and an optional menu section (e.g. "Female"). */
+export interface VoiceOption extends ParameterOption<string> {
+  group?: string;
 }
 
 /** See `ModelOption.falInput`. */
 export interface FalInputFormat {
   image?: "image_url" | "image_urls" | "start_image_url";
   aspectRatio?: "aspect_ratio" | "image_size";
+  /** Which field the prompt goes in. Most models take `prompt`; some text-to-speech models take the words as `text`. */
+  prompt?: "prompt" | "text";
 }
 
 /** How an edit's regions reach the model — see `ModelOption.regionFormat`. */
@@ -135,8 +163,8 @@ export type RegionFormat = "flux-3-boxes" | "text";
  * leaderboard categories at github.com/oolong-tea-2026/arena-ai-leaderboards,
  * so a future model-ranking lookup can join on it directly, plus
  * "text-to-text" for a plain text request (a Composer with no use case
- * picked). That repo has no audio-generation category at all, a real gap
- * for any future audio use case.
+ * picked). That repo has no audio-generation category, so "text-to-speech"
+ * and "text-to-music" have nothing to join on yet.
  */
 export type GenerationUseCase =
   | "text-to-image"
@@ -145,4 +173,6 @@ export type GenerationUseCase =
   | "image-to-video"
   | "video-edit"
   | "vision"
-  | "text-to-text";
+  | "text-to-text"
+  | "text-to-speech"
+  | "text-to-music";