inline-chat-kit 0.55.2 → 0.57.0

package/CHANGELOG.md

@@ -8,6 +8,82 @@ The versions before 1.0 follow the pre-release convention: **a breaking change
 or new public API bumps the minor**, and the patch is for fixes. Anything that would break an
 existing install is called out under **Breaking**, with what to do about it.
 
+## 0.57.0 — 2026-09-22
+
+A pane the host draws itself. `ChatExperience` placed its artifact pane beside
+the conversation and held which one was open, which is right until the host has
+a layout of its own. Nothing changes for a host that passes none of this.
+
+### Added
+
+- **`openArtifactId` and `onOpenArtifactChange` on `ChatExperience`.** Which
+  artifact is open, held by the host. Left out, the component keeps its own;
+  `null` is a held "none open". The change callback fires either way.
+- **`pane="inline" | "none"` on `ChatExperience`.** `"none"` draws no
+  `ArtifactPane`, reserves no width for one and never calls `artifact`; a
+  pressed card only reports its id, and still shows it is open from
+  `openArtifactId`.
+- **`openArtifact(id)` and `closeArtifact()` in `renderPart`'s context**, next
+  to `turnId` — so a host's own card can open the pane. `CustomPartContext` is
+  exported. `ChatTurnRow` takes `onArtifactChange` for the same when assembled
+  by hand.
+- **`ArtifactPane` outside `ChatLayout`**, documented and tested: a region with
+  focus on its title when it mounts, no trap and no Escape unless `modal`.
+- **`surface="flush" | "panes"` on `ChatExperience` and `ChatLayout`.**
+  `"panes"` makes the conversation a card of its own, so the pane beside it —
+  the kit's or the host's — is a second surface rather than a strip cut off the
+  same one. Both are drawn from the same tokens, and `--ick-chat-pane-inset` is
+  both the ring of space around them and the gap between them. Below the
+  layout's breakpoint the corners and the inset go, where the pane is a sheet.
+  `"flush"` is the default and is what the kit drew before.
+
+## 0.56.0 — 2026-09-22
+
+Four things that kept the kit out of a real host app: an answer could only
+hold the kit's own parts, an approval always offered "forever", an assembled
+chat could not be translated, and it drew controls a host had no use for.
+Nothing here changes what an existing install draws.
+
+### Added
+
+- **`{ kind: "custom", id, type, data }` — the host's own card in an answer.**
+  Every other part is a component in this package; this one is drawn by the
+  new `renderPart(part, { turnId })` prop on `ChatTurnRow` and
+  `ChatExperience`, in its place among the other parts and inside the answer's
+  entrance. Merged by id like the rest, so `{ kind: "custom", id, data }`
+  replaces `data` and keeps `type`. Without a renderer, or when it returns
+  `null`, the part draws nothing. `CustomPart` is exported.
+- **`chat` on `ChatExperience`.** It called `useChatTurns` itself, so a host
+  had no `updatePart` and a card could not change after the answer finished.
+  Pass your own hook's result and it is used instead; left out, nothing
+  changes. `onSend` is optional when `chat` is given.
+- **`choices` on `<Approval>` and on the approval part.** `["once", "deny"]`
+  leaves "Always allow" out. Allow once stays the primary and Deny stays first.
+  `ApprovalChoice` is exported.
+- **`labels` on `ChatExperience` and `ChatTurnRow`, and `LabelsProvider`.** One
+  `ChatLabels` object, grouped by component and partial, reaches every piece
+  through context — the header, the composer and its menu, the microphone and
+  what it announces, the highlighter, the thread, the code block's copy, the
+  pane, the jump button, the option letters, and every part. The strings that
+  were hard-coded English with no way in now all go through it.
+  `defaultLabels` is the English set. The individual `labels` props keep
+  working and win over the provider.
+- **`headerActions` and `composerMenu` on `ChatExperience`.**
+  `headerActions={false}` (or `["theme"]`, `["share"]`) drops the built-in
+  header actions; `composerMenu={false}` removes the "+", and a list of
+  `{ id, label, icon?, onSelect? }` replaces its three entries. `ChatInput`
+  takes the same list as `menu`. `ComposerMenuItem` is exported.
+
+### Fixed
+
+- **Every row in `ChatExperience` re-rendered on every frame of an answer.**
+  `onOpenArtifact` was an arrow written inline in the rows' props — a new
+  function each render — so `ChatTurnRow`'s memo never held inside the
+  assembled experience. Hoisted; the custom-part test fails without it.
+- **The composer's menu opened the file picker by matching the word "Add".**
+  Translated, it would have stopped attaching anything. It matches the entry's
+  id now.
+
 ## 0.55.2 — 2026-09-16
 
 ### Fixed

package/README.md

@@ -153,6 +153,14 @@ Which is why the callbacks take the turn's id rather than being closed over per
 row. Pass the hook's own functions straight through — they are stable. An arrow
 created during render is not, and hands the memo a new prop every time.
 
+`renderPart` is a callback like the others and follows the same rule: define
+it outside the component, or wrap it in `useCallback` / `useMemo`. A renderer
+written inline is a new function every render, which is a changed prop on every
+row — so every finished answer re-renders on every frame of the one arriving,
+exactly the cost the memo exists to remove. What a card needs to change (it was
+applied, it was sent) belongs in the part's `data`, written back with
+`updatePart`; then only the row that owns it re-renders.
+
 If you write your own row instead, wrap it in `React.memo` and do the same.
 
 ## The four states
@@ -217,6 +225,9 @@ input that morphs into its own bubble rather than a record of what was typed.
 | `onFeedback` | `(id, verdict) => void` | | Draws the thumbs |
 | `feedback` | `"up" \| "down" \| null` | `null` | Which one is lit |
 | `answerActions` | `boolean` | `true` | Leave the row out |
+| `renderPart` | `(part, { turnId }) => ReactNode` | | Draws `custom` parts — see below. Keep it stable |
+| `composerMenu` | `ComposerMenuItem[] \| false` | built-in three | The composer's "+" menu; `false` removes the "+" |
+| `labels` | `ChatLabels` | English | Every word the row says — see [Labels](#labels-every-word-the-kit-says) |
 
 The live row carries **`data-active-input`**, so a page can style the composer
 without knowing which turn it is. The case it exists for: a gradient fading the
@@ -411,15 +422,49 @@ component that owns it.
 | `tasks` | `<TaskList>` | `title`, `tasks`, `collapsible` |
 | `chain` | `<ChainOfThought>` | `steps`, `state`, `duration` |
 | `sources` | `<Sources>` | `sources`, `title`, `collapsible` |
-| `approval` | `<Approval>` | `title`, `description`, `tool`, `decision` |
+| `approval` | `<Approval>` | `title`, `description`, `tool`, `decision`, `choices` |
 | `question` | `<QuestionGroup>` | `title`, `questions`, `answers`, `activeIndex`, `collapsible` |
 | `notice` | `<SystemMessage>` | `text`, `tone` |
 | `artifact` | `<ArtifactCard>` | `title`, `meta`, `preview`, `lang`, `content`, `state` |
+| `custom` | whatever `renderPart` returns | `type`, `data` — the host's own card |
 
 `reasoning` and `chain` are the same job at two grains — a block of prose, or
 steps that follow from one another. Sending both for one stretch of thinking
 says it twice.
 
+#### Your own cards: `custom`
+
+Every other kind is a component in this package. `custom` is the host's: `type`
+says which of your cards it is, `data` is whatever that card needs, and
+`renderPart` draws it — in its place among the other parts, inside the answer
+and its entrance.
+
+```tsx
+import type { CustomPart } from "inline-chat-kit";
+
+// Streamed like any part…
+yield { kind: "custom", id: "plan", type: "plan-diff", data: { changes, status: "proposed" } };
+
+// …drawn by the host. Outside the component, so it is stable.
+const renderPart = (part: CustomPart, { turnId }: { turnId: string }) =>
+  part.type === "plan-diff" ? <PlanDiff turnId={turnId} id={part.id} {...(part.data as PlanDiffData)} /> : null;
+
+// …and changed after the answer has finished, by id. Only `data` is replaced.
+updatePart(turnId, { kind: "custom", id: "plan", data: { changes, status: "applied" } });
+```
+
+Without `renderPart`, or when it returns `null`, the part draws nothing — no
+placeholder, no error. A type the host does not recognise is a type it chose
+not to draw. `data` is replaced whole on an update, not merged: it is yours,
+and the kit does not guess its shape.
+
+`ChatExperience` calls `useChatTurns` itself, so a host using it passes its own
+instead — `chat={useChatTurns({ onSend })}` — to hold `updatePart`.
+
+The second argument to `renderPart` is `{ turnId, openArtifact, closeArtifact }`
+(`CustomPartContext`), so a card can open the pane — see
+[Drawing the pane yourself](#drawing-the-pane-yourself).
+
 #### Citing a source from the prose
 
 `[^1]` in the answer is a **citation marker**, and the number is a position in
@@ -567,6 +612,7 @@ can already see.
 | `decision` | `"once" \| "always" \| "denied" \| null` | `null` while it is still asking |
 | `onDecide` | `(decision) => void` | |
 | `readOnly` | `boolean` | A record of a decision made elsewhere |
+| `choices` | `("once" \| "always" \| "deny")[]` | Which answers are offered. All three by default |
 
 **Three answers, not two.** "Yes" and "yes forever" are not the same answer,
 and a UI offering one button for both collects the wrong one. **Allow once is
@@ -578,6 +624,15 @@ too, so a keyboard reaches the safe answer without tabbing past the other two.
 It turns red only under the pointer, because a permanently red button is the
 first thing the eye lands on.
 
+**Two answers, where "forever" means nothing.** Applying one change to a plan
+happens once; `choices={["once", "deny"]}` leaves "Always allow" out. Nothing
+else moves: Allow once is still the primary, Deny is still first in the DOM and
+alone on the left, and the record it settles into says only what was decided.
+
+```tsx
+<Approval title="Apply the change to your plan" choices={["once", "deny"]} onDecide={decide} />
+```
+
 Give it something to show. An approval with nothing under it is asking for a
 signature on a blank page.
 
@@ -586,7 +641,7 @@ decided. Live controls under a decision already made invite a second one that
 contradicts the first.
 
 As a `TurnPart` it is `{ kind: "approval", id, title, description?, tool?,
-decision? }` — data, like every part, so the tool it names is drawn for it
+decision?, choices? }` — data, like every part, so the tool it names is drawn for it
 rather than passed in as an element. `<ChatTurnRow>` reports through
 `onDecideApproval`.
 
@@ -977,6 +1032,7 @@ between products, and the only part.
 | `onOpen` | `(id: string) => void` | Without one the card is a record, not a control |
 | `<ArtifactPane>` `modal` | `boolean` | See below |
 | `<ChatLayout>` `pane` | `({ narrow }) => ReactNode` | |
+| `<ChatLayout>` `surface` | `"flush" \| "panes"` | One surface, or two. See below |
 
 **`modal` is the one prop that changes behaviour, and it is not about
 position.** Covering the conversation changes what the pane *is*: focus has to
@@ -990,6 +1046,78 @@ That is the part worth having in a library rather than the box. On open, focus
 moves to the pane's heading — not into its first control, which would skip what
 the thing is — and it is **not** trapped unless the pane is covering the chat.
 
+#### Two panes, not one page split in half
+
+By default the conversation fills the layout and the pane is the only card on
+it — which is what a chat that owns the whole window wants. `surface="panes"`
+makes the conversation a card of its own instead:
+
+```tsx
+<ChatExperience onSend={send} surface="panes" artifact={artifact} />
+```
+
+Both surfaces are drawn from the same tokens — `--ick-chat-pane-surface` is
+`--ick-artifact-pane-surface`, and the radius follows — because two panes side
+by side have to be the same *kind* of thing, or the chat reads as the
+background and the pane as a dialog over it. One number,
+`--ick-chat-pane-inset`, is the ring of space around both and the gap between
+them, so the frame is even the whole way round. No divider: the gap is what
+says there are two of them.
+
+Below `<ChatLayout>`'s breakpoint the corners and the inset go: the pane is a
+sheet over the conversation there, and a card inside a card with a sheet over
+both is three surfaces for one screen.
+
+Inside the card, `--ick-page` is the card — so the header's tint and the fades
+at both ends end in the colour they are standing on rather than in the ground
+outside it.
+
+#### Drawing the pane yourself
+
+`ChatExperience` places the pane beside the conversation. A host with a layout
+of its own — its own column, a drawer, a route — holds which artifact is open
+and tells the kit to keep out of the way:
+
+```tsx
+const [openId, setOpenId] = useState<string | null>(null);
+const open = openId ? findArtifact(openId) : null;
+
+<div className="workspace">
+  <ChatExperience
+    chat={chat}
+    pane="none"                        // no pane here, and no room made for one
+    openArtifactId={openId}            // the cards still show which one is open
+    onOpenArtifactChange={setOpenId}   // a card pressed, or a custom card's openArtifact
+    renderPart={renderPart}
+  />
+  {open && (
+    <aside className="my-column">
+      <ArtifactPane key={openId} title={open.title} onClose={() => setOpenId(null)}>
+        {open.body}
+      </ArtifactPane>
+    </aside>
+  )}
+</div>
+```
+
+- **`openArtifactId` / `onOpenArtifactChange`** hold the state outside. Left
+  out, `ChatExperience` keeps its own, as before. `null` is a held "nothing
+  open"; only `undefined` means "not held". `onOpenArtifactChange` is called
+  either way, so a host can listen without holding.
+- **`pane="none"`** draws no `ArtifactPane`, makes no room for one and never
+  calls `artifact`. Pressing a card reports the id (pressing the open one again
+  reports `null`).
+- **A custom card opens one too.** `renderPart`'s second argument carries
+  `openArtifact(id)` and `closeArtifact()`, next to `turnId`: a caregiver in
+  your card opens her profile the way an `ArtifactCard` opens a plan.
+- **`surface="panes"` goes with it.** The conversation becomes a card, your
+  pane is the second one, and the two match without your having to copy the
+  kit's radius and shadow.
+- **`<ArtifactPane>` stands on its own.** Outside `ChatLayout` leave `modal`
+  off: it is a region, focus moves to its title when it mounts, and it neither
+  traps focus nor takes Escape. Key it by the artifact's id, so opening a
+  different one is a new pane — and focus moves to the new title.
+
 ### `<SystemMessage>`
 
 The conversation saying something about itself — not the reader, not the agent.
@@ -1266,6 +1394,63 @@ existing call sites keep working. Its `s` / `m` / `l` map to `m` / `l` / `xl`.
 Neither takes a dark-mode prop: the theme is a token swap on an ancestor. See
 [theming.md](./theming.md).
 
+## Labels: every word the kit says
+
+Every component takes a `labels` prop, and `ChatExperience` and `ChatTurnRow`
+take one object for all of them — grouped by the component that says it, and
+partial: anything left out stays English.
+
+```tsx
+import { ChatExperience, type ChatLabels } from "inline-chat-kit";
+
+const sr: ChatLabels = {
+  input: { placeholder: "Pitaj bilo šta…", send: "Pošalji poruku", copy: "Kopiraj", edit: "Izmeni" },
+  approval: { once: "Dozvoli jednom", deny: "Odbij", allowedOnce: "Dozvoljeno jednom", wasDenied: "Odbijeno" },
+  reasoning: { thinking: "Razmišljam", thoughtFor: "Razmišljao" },
+  answerActions: { copy: "Kopiraj odgovor", regenerate: "Ponovo" },
+  tasks: { progress: "{done} od {total}" },
+};
+
+<ChatExperience onSend={send} labels={sr} />;
+```
+
+What counts as a word: text on screen, an `aria-label`, a `title`, a
+placeholder, text only a screen reader gets, and what is said through the live
+region. `{name}` in a value is filled in — keep it, and move it wherever the
+language wants it. `defaultLabels` is the full English set, which is also the
+list of what there is to translate.
+
+It travels by context, not by a prop on every row, so the rows' memo is not
+disturbed. For pieces assembled by hand, `LabelsProvider` does what
+`ChatExperience` does:
+
+```tsx
+<LabelsProvider labels={sr}>
+  {turns.map((turn) => <ChatTurnRow key={turn.id} turn={turn} /* … */ />)}
+</LabelsProvider>
+```
+
+The value is compared by content, so an object written inline costs nothing
+after the first render. A component's own `labels` prop wins over the provider
+for that one instance.
+
+### Turning off what you do not use
+
+`ChatExperience` draws a theme toggle and Share in the header and a "+" menu in
+the composer. A host that has none of those says so:
+
+```tsx
+<ChatExperience
+  onSend={send}
+  headerActions={false}          // or ["theme"], or ["share"]
+  composerMenu={false}           // or your own: [{ id, label, icon?, onSelect }]
+/>
+```
+
+The saved highlights button is not one of the header's actions — it appears
+only once there is a highlight, and it is the only way back to them. An entry in
+your own menu with id `"attach"` and no `onSelect` opens the file picker.
+
 ## Theming
 
 The kit reads CSS custom properties, all prefixed `--ick-`. That is the whole

package/dist/Approval/Approval.d.ts

@@ -1,7 +1,10 @@
 import { HTMLAttributes, ReactNode } from 'react';
+import { ApprovalLabels } from '../labels/labels';
 /** Once, every time from now on, or not at all. */
 export type Decision = "once" | "always" | "denied";
-type Labels = Record<"once" | "always" | "deny", string> & Record<"allowedOnce" | "allowedAlways" | "wasDenied" | "pending", string>;
+/** The buttons, by what they answer. `"deny"` is the button; `"denied"` the record. */
+export type ApprovalChoice = "once" | "always" | "deny";
+type Labels = ApprovalLabels;
 export interface ApprovalProps extends Omit<HTMLAttributes<HTMLElement>, "title"> {
     /** What is being asked. One line: "Run a command in your shell". */
     title: ReactNode;
@@ -20,6 +23,14 @@ export interface ApprovalProps extends Omit<HTMLAttributes<HTMLElement>, "title"
     onDecide?: (decision: Decision) => void;
     /** Nothing can be decided from here — a record of a decision already made. */
     readOnly?: boolean;
+    /**
+     * Which answers are offered. All three when left out.
+     *
+     * Leave out `"always"` where a standing permission means nothing — applying
+     * one edit to a plan is a thing that happens once. "Allow once" stays the
+     * primary and Deny stays first; only the button that is not offered goes.
+     */
+    choices?: ApprovalChoice[];
     labels?: Partial<Labels>;
 }
 /**
@@ -38,5 +49,5 @@ export interface ApprovalProps extends Omit<HTMLAttributes<HTMLElement>, "title"
  * decided. Leaving live controls under a decision already made invites a
  * second, contradictory one.
  */
-export declare function Approval({ title, description, children, decision, onDecide, readOnly, labels, className, ...rest }: ApprovalProps): import("react").JSX.Element;
+export declare function Approval({ title, description, children, decision, onDecide, readOnly, choices, labels, className, ...rest }: ApprovalProps): import("react").JSX.Element;
 export {};

package/dist/Artifact/ArtifactPane.d.ts

@@ -47,4 +47,4 @@ export interface ArtifactPaneProps extends Omit<HTMLAttributes<HTMLDivElement>,
  * conversation, and it must **not** be trapped unless the pane is covering
  * that conversation. Every host gets one of those two wrong.
  */
-export declare function ArtifactPane({ title, meta, children, onClose, modal, expanded, onToggleExpanded, closeLabel, expandLabel, collapseLabel, className, ...rest }: ArtifactPaneProps): import("react").JSX.Element;
+export declare function ArtifactPane({ title, meta, children, onClose, modal, expanded, onToggleExpanded, closeLabel: closeProp, expandLabel: expandProp, collapseLabel: collapseProp, className, ...rest }: ArtifactPaneProps): import("react").JSX.Element;

package/dist/Artifact/ChatLayout.d.ts

@@ -28,6 +28,19 @@ export interface ChatLayoutProps extends HTMLAttributes<HTMLDivElement> {
      * it out and the sheet has neither, which is a sheet a thumb cannot dismiss.
      */
     onDismiss?: () => void;
+    /**
+     * Whether the conversation is a surface of its own.
+     *
+     * `"flush"` (the default): the conversation fills the layout and the pane is
+     * the only card — which is what a chat that owns the whole window wants.
+     *
+     * `"panes"`: two cards side by side on the page, with the same ring of space
+     * around both and the same gap between them. A divider would have said the
+     * same thing more cheaply and less truthfully: these are two surfaces, not
+     * one surface with a line through it. The pane the host draws itself goes
+     * beside a `"panes"` conversation and looks like it belongs there.
+     */
+    surface?: "flush" | "panes";
 }
 /**
  * Where the pane goes, decided once.
@@ -41,4 +54,4 @@ export interface ChatLayoutProps extends HTMLAttributes<HTMLDivElement> {
  * What is left open is the part that actually differs — what is *in* the pane.
  * See `ArtifactPane`.
  */
-export declare function ChatLayout({ children, pane, onDismiss, className, ...rest }: ChatLayoutProps): import("react").JSX.Element;
+export declare function ChatLayout({ children, pane, onDismiss, surface, className, ...rest }: ChatLayoutProps): import("react").JSX.Element;

package/dist/Attachments/Attachments.d.ts

@@ -1,4 +1,5 @@
 import { HTMLAttributes } from 'react';
+import { LabelsOf } from '../labels/labels';
 /** Something sent along with a message. */
 export interface Attachment {
     id: string;
@@ -16,9 +17,7 @@ export interface Attachment {
     /** In bytes. Shown beside the name. */
     size?: number;
 }
-type Labels = {
-    remove: string;
-};
+type Labels = LabelsOf<"attachments">;
 export interface AttachmentsProps extends Omit<HTMLAttributes<HTMLUListElement>, "onRemove"> {
     attachments: Attachment[];
     /**

package/dist/Branch/Branch.d.ts

@@ -1,10 +1,6 @@
 import { HTMLAttributes } from 'react';
-type Labels = {
-    previous: string;
-    next: string;
-    /** `{index}` and `{total}` are filled in. */
-    position: string;
-};
+import { LabelsOf } from '../labels/labels';
+type Labels = LabelsOf<"branch">;
 export interface BranchProps extends Omit<HTMLAttributes<HTMLDivElement>, "onSelect"> {
     /** How many answers this turn has had. */
     total: number;

package/dist/ChainOfThought/ChainOfThought.d.ts

@@ -1,5 +1,6 @@
 import { HTMLAttributes, ReactNode } from 'react';
 import { WorkState } from '../stateGlyph/StateGlyph';
+import { LabelsOf } from '../labels/labels';
 /** One step of a derivation: what was worked out, and the working. */
 export interface Thought {
     id: string;
@@ -10,13 +11,7 @@ export interface Thought {
     /** Defaults to `done`: a step you can read is a step that happened. */
     state?: WorkState;
 }
-type Labels = {
-    /** Followed by the count: "Thought through 4 steps". */
-    through: string;
-    step: string;
-    steps: string;
-    thinking: string;
-};
+type Labels = LabelsOf<"chain">;
 export interface ChainOfThoughtProps extends Omit<HTMLAttributes<HTMLElement>, "title"> {
     steps: Thought[];
     /** The chain as a whole. `thinking` holds it open and narrates the last step. */

package/dist/ChatExperience/ChatExperience.d.ts

@@ -1,11 +1,13 @@
 import { ReactNode } from 'react';
 import { ChatHeaderAction } from '../ChatHeader/ChatHeader';
 import { ReplyThreadPopupProps } from '../ReplyThreadPopup/ReplyThreadPopup';
-import { UseChatTurnsOptions } from '../useChatTurns/useChatTurns';
+import { UseChatTurnsOptions, UseChatTurnsResult } from '../useChatTurns/useChatTurns';
 import { FoldMotion } from '../QuestionGroup/QuestionGroup';
 import { InlineAnimConfig } from '../ChatInput/ChatInput';
 import { TranscribeHandler } from '../voice/useVoiceInput';
-import { TurnPartUpdate } from '../turnParts/turnParts';
+import { CustomPart, CustomPartContext, TurnPartUpdate } from '../turnParts/turnParts';
+import { ComposerMenuItem } from '../ChatInput/AddCardsOverlay';
+import { ChatLabels } from '../labels/labels';
 import { Answer } from '../QuestionCard/types';
 import { Decision } from '../Approval/Approval';
 /**
@@ -60,10 +62,48 @@ export interface ChatExperienceArtifact {
 }
 /** A part the host drives, handed the writer for the turn it belongs to. */
 export type PartWriter = (turnId: string, part: TurnPartUpdate) => void;
+/** The header's built-in actions, by id. */
+export type ChatExperienceHeaderAction = "theme" | "share";
 export interface ChatExperienceProps {
     /** Where answers come from. Return a string, a promise of one, or an async
-        iterable of deltas — see `useChatTurns`. */
-    onSend: UseChatTurnsOptions["onSend"];
+        iterable of deltas — see `useChatTurns`. Required unless `chat` is
+        given, which brings its own. */
+    onSend?: UseChatTurnsOptions["onSend"];
+    /**
+     * The conversation, held by the host.
+     *
+     * Left out, this component calls `useChatTurns` itself and nothing outside
+     * can reach the turns. Pass what your own `useChatTurns` returned and the
+     * host has the same handle this does — `updatePart` in particular, which is
+     * how a card in an answer changes after the answer has finished ("Apply" →
+     * "Applied"). `onSend` is ignored then; the hook you called has one.
+     */
+    chat?: UseChatTurnsResult;
+    /**
+     * Draws the host's own `{ kind: "custom" }` parts. See `ChatTurnRow`. Keep
+     * it stable — outside the component or in `useCallback` — or every row
+     * re-renders on every frame of an answer arriving.
+     */
+    renderPart?: (part: CustomPart, context: CustomPartContext) => ReactNode;
+    /**
+     * Every word the chat says, grouped by the component that says it. Partial:
+     * anything left out stays English. Reaches every piece through context, so
+     * an inline object costs nothing — it is compared by content.
+     */
+    labels?: ChatLabels;
+    /**
+     * The header's built-in actions. `true` (the default) is the theme toggle
+     * and Share; `false` is neither; a list keeps only those named. The saved
+     * highlights button is not one of these — it appears only once there is a
+     * highlight, and it is the only way back to them. `actions` still adds your
+     * own after whatever is left.
+     */
+    headerActions?: boolean | ChatExperienceHeaderAction[];
+    /**
+     * The composer's "+" menu. `false` takes the "+" away; a list replaces the
+     * built-in three (Add, Design, Connectors). Keep a list stable.
+     */
+    composerMenu?: ComposerMenuItem[] | false;
     /** Speech to text. The kit records; the host transcribes. Omit and the
         microphone does not appear. */
     onTranscribe?: TranscribeHandler;
@@ -85,6 +125,31 @@ export interface ChatExperienceProps {
     contextBase?: number;
     /** The pane beside the conversation, asked for the artifact that is open. */
     artifact?: (openId: string) => ChatExperienceArtifact | null;
+    /**
+     * Which artifact is open, held by the host. Left out (`undefined`), this
+     * component keeps it. `null` is "none open" — held, just empty.
+     */
+    openArtifactId?: string | null;
+    /** Somebody opened or closed one — a card pressed, the pane's X, a custom
+        card calling `openArtifact`. Called whether or not the state is held. */
+    onOpenArtifactChange?: (id: string | null) => void;
+    /**
+     * Who draws the pane. `"inline"` (the default): this component, beside the
+     * conversation, from `artifact`. `"none"`: nobody here — no pane, no room
+     * made for one. The cards still open and still show which one is open;
+     * the host draws the pane wherever its own layout wants it, usually with
+     * `openArtifactId` and `<ArtifactPane>`.
+     */
+    pane?: "inline" | "none";
+    /**
+     * Whether the conversation is a card of its own.
+     *
+     * `"flush"` (the default) fills the window, as before. `"panes"` makes it a
+     * surface on the page, so the pane beside it — the kit's or the host's own —
+     * is a second surface rather than a strip cut off the same one. See
+     * `ChatLayout`.
+     */
+    surface?: "flush" | "panes";
     /** The theme, if the host keeps it. Left off, this manages its own and puts
         a toggle in the header; `data-theme` on the root element either way, and
         unset until somebody chooses, so the kit follows the system preference —
@@ -112,4 +177,4 @@ export interface ChatExperienceProps {
     onDecideApproval?: (write: PartWriter, turnId: string, partId: string, decision: Decision) => void;
     className?: string;
 }
-export declare function ChatExperience({ onSend, onTranscribe, onThreadReply, title, backHref, backLabel, actions, placeholder, empty, contextTotal, contextBase, artifact, theme: themeProp, onThemeChange, cursor, selectionToggle, anchorOffset, endOffset, animationConfig, foldMotion, feedDelay, onAnswerQuestion, onEditQuestion, onDecideApproval, className, }: ChatExperienceProps): import("react").JSX.Element;
+export declare function ChatExperience({ onSend, chat: hostChat, renderPart, labels, headerActions: builtInActions, composerMenu, onTranscribe, onThreadReply, title: titleProp, backHref, backLabel, actions, placeholder, empty, contextTotal, contextBase, artifact, openArtifactId: openArtifactProp, onOpenArtifactChange, pane: paneMode, surface, theme: themeProp, onThemeChange, cursor, selectionToggle, anchorOffset, endOffset, animationConfig, foldMotion, feedDelay, onAnswerQuestion, onEditQuestion, onDecideApproval, className, }: ChatExperienceProps): import("react").JSX.Element;