inline-chat-kit 0.56.0 → 0.58.0

package/CHANGELOG.md

@@ -8,6 +8,76 @@ 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.58.0 — 2026-09-23
+
+The composer at the bottom, as an alternative to the inline one — roadmap I2.
+One prop; nothing changes for a host that does not pass it.
+
+### Added
+
+- **`composer="inline" | "docked"` on `ChatExperience`.** `"docked"` keeps the
+  input at the bottom edge and stacks the conversation above it. The live
+  input is still the last turn, so a sent message still becomes its bubble —
+  the same element, carried up into the conversation by its layout animation
+  as a fresh composer takes its place. A sent message is still brought to the
+  top of the view and held there while its answer is written, as it is inline;
+  the composer stays on the bottom edge while that happens, and the workspace
+  gives up whatever a phone's keyboard covers.
+- **`nextTurn: "after-answer" | "at-send"` on `useChatTurns`.** `"at-send"`
+  opens the next input the moment a message goes, so it can be typed into
+  while the answer arrives. A send while one is in flight is now refused in
+  either mode: it used to start a second run and take the first one's abort
+  away.
+- **`busy` on `ChatInput` and `ChatTurnRow`.** Open to type into, closed to
+  send from: Enter does nothing, the send glyph is a stop when there is an
+  `onStop` and inert when there is not.
+- **`dock` on `Conversation`.** The last child is pinned to the bottom of the
+  view — an auto margin while the content is short, `sticky` once it is long —
+  and the room an anchor needs is put above it rather than below, where
+  `sticky` could not hold it.
+
+- **`highlights` and `bookmarks` on `ChatExperience`, `highlights` on
+  `ChatTurnRow`, `marking` on `TextHighlighter`.** `highlights={false}` draws
+  answers as prose — no marker layer, nothing over the text in the tab order,
+  no highlight menu — and takes the saved highlights and the selection-mode
+  pair with it. `bookmarks={false}` keeps marking and drops the keeping. Both
+  are decided in code rather than offered in the interface, which is also how
+  `composer`, `pane`, `surface`, `headerActions` and `composerMenu` work.
+
+### Fixed
+
+- **A responding bubble drew a stop with nothing behind it** when the host
+  had not passed `onStop`. It is drawn only with somewhere to report to.
+
+## 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

package/README.md

@@ -216,6 +216,7 @@ input that morphs into its own bubble rather than a record of what was typed.
 | `onDraft` | `(id, value) => void` | | |
 | `onSubmit` | `(id, value) => void` | | |
 | `onStop` | `() => void` | | |
+| `busy` | `boolean` | | An answer is arriving elsewhere: the composer offers a stop, not a send |
 | `onEdit` | `(id) => void` | | |
 | `onCancelEdit` | `(id) => void` | | |
 | `onCopy` | `(value) => void` | writes to the clipboard | |
@@ -250,6 +251,53 @@ Every callback is optional; a row with none of them renders and can be marked.
 The row carries `id="turn-<id>"` so a host can scroll to one, and `aria-busy`
 while its answer is arriving.
 
+### The composer at the bottom
+
+The kit's argument is that the input is the message: it stands at the end of
+the conversation and becomes the bubble where you typed it. Some products want
+the shape every other chat has instead — the box at the bottom, the
+conversation stacking above it. That is one prop, not a second kit:
+
+```tsx
+<ChatExperience onSend={send} composer="docked" />
+```
+
+What changes, and what does not:
+
+- **The box stays at the bottom.** `Conversation` pins its last child there —
+  pushed down by an auto margin while the conversation is shorter than the
+  view, held by `position: sticky` once it is longer. Both put its bottom on
+  the same edge, so nothing moves when the conversation crosses from one to
+  the other.
+- **It still becomes the bubble.** The live input *is* the last turn, as it
+  always was, so the morph is the one the kit already has. What is new is the
+  travel: a fresh composer takes the last place, the sent one is no longer
+  last and no longer sticky, and its `layout` animation carries it up into the
+  conversation where it now belongs.
+- **The next question can be typed while this one is answered.**
+  `useChatTurns` opens the next input at send rather than at settle
+  (`nextTurn: "at-send"`), the composer is `busy` while the answer arrives —
+  Enter does nothing and the send glyph is a stop — and a send while an answer
+  is in flight is refused rather than started on top of it. Queueing it is a
+  separate thing.
+- **A sent message still goes to the top.** The same anchor the inline
+  composer uses: your question is brought to the top of the view and held
+  there while its answer is written underneath. The composer does not move
+  with it — it is `sticky`, so the room the anchor scrolls into passes behind
+  it. The room itself goes *above* the dock rather than below: `sticky` only
+  ever pulls an element up, so room underneath would leave the composer
+  stranded in the middle of the view.
+- **The keyboard is allowed for.** On a phone the software keyboard comes up
+  over the bottom edge; the workspace gives up what `visualViewport` says is
+  covered, so the composer rides on the keyboard's top edge.
+- Everything else is the same: the parts, the pane, the highlighter, editing
+  a sent message in place, `labels`, `surface="panes"`.
+
+With a `chat` of your own, give its hook `nextTurn: "at-send"`. Assembling the
+rows by hand, the same shape is `<Conversation dock>` with the live row last,
+`busy={isStreaming}` on it, and `onStop` on it rather than on the bubble being
+answered.
+
 ### Two rules everything follows
 
 **Surfaces nest in three steps.** A **ground** is what a group of things sits
@@ -461,6 +509,10 @@ 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
@@ -947,6 +999,7 @@ instant the reader scrolls away, with a button offering the way back.
 | `scrollButton` | `boolean` | `true` | The way back |
 | `scrollButtonLabel` | `string` | `"Jump to the latest"` | |
 | `follow` | `boolean` | `true` | `false` makes it a plain scroll container |
+| `dock` | `boolean` | `false` | The last child is pinned to the bottom edge — see [The composer at the bottom](#the-composer-at-the-bottom) |
 | `className` | `string` | | Goes on the root, which is the box you lay out |
 | `viewportClassName` | `string` | | Goes on the element that scrolls — padding belongs here |
 
@@ -1028,6 +1081,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
@@ -1041,6 +1095,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.
@@ -1359,17 +1485,36 @@ 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:
+Everything here is decided **in code**, not offered in the interface. A
+product either marks passages or it does not, keeps a theme toggle or does
+not; a control for choosing is a question nobody asked.
 
 ```tsx
 <ChatExperience
   onSend={send}
+  composer="docked"              // or "inline", the default
+  highlights={false}             // no marker layer, no highlight menu, no saved ones
+  bookmarks={false}              // marking stays, keeping goes
   headerActions={false}          // or ["theme"], or ["share"]
   composerMenu={false}           // or your own: [{ id, label, icon?, onSelect }]
+  pane="none"                    // draw the artifact pane yourself
+  surface="panes"                // the conversation as a card of its own
 />
 ```
 
+| Prop | Off means |
+| --- | --- |
+| `highlights={false}` | Answers are prose: no marker layer, nothing over the text in the tab order, no highlight menu — and no saved highlights or selection-mode pair, since both are about marking |
+| `bookmarks={false}` | A passage can still be marked and replied to; nothing is kept. Use `onHighlight` to keep them yourself |
+| `onThreadReply` omitted | No threads. A thread is opened from a highlight, so `highlights={false}` takes them too |
+| `headerActions={false}` | No theme toggle, no Share. Your own `actions` are unaffected |
+| `composerMenu={false}` | No "+" in the composer |
+| `selectionToggle` omitted | No marker/precise pair in the header (the default) |
+| `cursor` omitted | No pointer-following cursor (the default) |
+
+Assembling the rows by hand, the same switch is `highlights` on
+`<ChatTurnRow>`, which is `marking` on `<TextHighlighter>`.
+
 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.

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/ChatExperience/ChatExperience.d.ts

@@ -5,7 +5,7 @@ import { UseChatTurnsOptions, UseChatTurnsResult } from '../useChatTurns/useChat
 import { FoldMotion } from '../QuestionGroup/QuestionGroup';
 import { InlineAnimConfig } from '../ChatInput/ChatInput';
 import { TranscribeHandler } from '../voice/useVoiceInput';
-import { CustomPart, 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';
@@ -84,9 +84,7 @@ export interface ChatExperienceProps {
      * it stable — outside the component or in `useCallback` — or every row
      * re-renders on every frame of an answer arriving.
      */
-    renderPart?: (part: CustomPart, context: {
-        turnId: string;
-    }) => ReactNode;
+    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
@@ -127,6 +125,48 @@ 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";
+    /**
+     * Where the composer lives.
+     *
+     * `"inline"` (the default): the input is the message. It stands at the end
+     * of the conversation, and what you type becomes the bubble where you typed
+     * it — the argument this kit makes.
+     *
+     * `"docked"`: the input stays at the bottom of the view, the way most chats
+     * keep it, and the conversation stacks above it. Sent, it still becomes the
+     * bubble — the same element, travelling into the conversation — and a fresh
+     * one takes its place at the bottom straight away, so the next question can
+     * be typed while this one is being answered. Everything else is the same:
+     * the parts, the pane, the highlighter, editing in place.
+     *
+     * With a `chat` of your own, give its `useChatTurns` `nextTurn: "at-send"`.
+     */
+    composer?: "inline" | "docked";
     /** 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 —
@@ -136,8 +176,32 @@ export interface ChatExperienceProps {
     /** The pointer-following cursor, and the rule that hides the real one. Only
         ever where there is a pointer to replace. */
     cursor?: boolean;
-    /** The freeform-marker / precise-selection pair in the header. */
+    /** The freeform-marker / precise-selection pair in the header. Drawn only
+        where there is marking to choose a mode for. */
     selectionToggle?: boolean;
+    /**
+     * Whether an answer can be marked at all.
+     *
+     * On by default: a marker over a passage is how a reader asks about one
+     * sentence rather than the whole answer. `false` draws answers as prose —
+     * no marker layer, no highlight menu, nothing in the tab order over the
+     * text — and takes the saved highlights and the selection-mode pair with
+     * it, because both are about marking. A thread is opened from a highlight,
+     * so `onThreadReply` has nothing to open it from either.
+     *
+     * Set in code, not offered in the interface: a product either works this
+     * way or it does not.
+     */
+    highlights?: boolean;
+    /**
+     * Whether marked passages are kept.
+     *
+     * On by default, and only ever visible once there is one: the header grows
+     * a button with the count, and it opens the sheet that lists them.
+     * `false` keeps marking and threads and drops the keeping — for a host that
+     * would rather store them itself, through `onHighlight`.
+     */
+    bookmarks?: boolean;
     /** How far below the top edge a sent message comes to rest. Sets the
         conversation's own top padding too — the two have to agree, so one number
         writes both. */
@@ -154,4 +218,4 @@ export interface ChatExperienceProps {
     onDecideApproval?: (write: PartWriter, turnId: string, partId: string, decision: Decision) => void;
     className?: string;
 }
-export declare function ChatExperience({ onSend, chat: hostChat, renderPart, labels, headerActions: builtInActions, composerMenu, onTranscribe, onThreadReply, title: titleProp, 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, composer, theme: themeProp, onThemeChange, cursor, selectionToggle, highlights: marking, bookmarks, anchorOffset, endOffset, animationConfig, foldMotion, feedDelay, onAnswerQuestion, onEditQuestion, onDecideApproval, className, }: ChatExperienceProps): import("react").JSX.Element;