npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

inline-chat-kit

v0.63.2

Published

An inline AI chat experience for React. The input is the message: it morphs into the bubble, the answer streams beneath it, and the parts around it — tool calls, reasoning, questions, artifacts, dictation — come with it.

Readme

inline-chat-kit

An inline AI chat experience for React. The input is the message: when you send, the pill you typed into morphs into the bubble that holds your text, and the answer streams in below it. No separate composer, no jump cut.

Ships the surrounding pieces too — a turn row, a header for the conversation, hover actions on each bubble, copy and feedback under every answer, markdown answers you can draw on with a marker, syntax-highlighted code blocks, a scroll container that keeps up with an answer, and reply-in-thread popups.

New here? Getting started is one file, ten minutes, and a chat that runs with no backend. The rest of this page is the reference.

Where it is meant to run

Desktop and tablet. That is what this is designed for, tuned for, and what the checks measure.

It runs on a phone and does not break. The artifact pane becomes a bottom sheet, so does a reply thread; every control is reachable by a thumb; nothing zooms when a field takes focus; the type scale rises so reading text is 16px and the icons rise with it. There are guards for each of those, in two engines, at 390×844 — npm run zoom-check and npm run reach-check.

But it is not tuned for a phone, and the inline idea itself is weaker there. Worth saying plainly rather than leaving you to discover it.

The argument for an inline composer is that you see your question and its answer at once, because the thing you type into is the message. A phone gives you about half a screen once the keyboard is up — and the browser will not tell you how much. So the platform takes away the one thing the design exists for.

Four more that no amount of CSS reaches:

| | | | --- | --- | | the keyboard's height | the browser does not report it reliably; a native scroll view is simply told | | text selection | the system's own selection UI fights a marker drawn in prose — this kit ships a selection-mode toggle because of that | | scroll physics | rubber-banding and momentum belong to the browser, not to you | | haptics | no API at all on iOS Safari |

If you need a phone-first chat, treat this as a specification for one rather than an implementation of one. The parts that would carry over are the ones with no DOM in them — useChatTurns, turnParts, placePanel — and they are plain TypeScript on purpose.

Desktop applications are a different story: an Electron or Tauri renderer is a browser, so this works there today with nothing changed.

Install

npm install inline-chat-kit motion lucide-react

react, react-dom, motion and lucide-react are peer dependencies — the kit uses whatever copy your app already has.

Use

import { useState } from "react";
import { ChatInput, type ChatInputState } from "inline-chat-kit";
import "inline-chat-kit/styles.css";

function Composer() {
  const [value, setValue] = useState("");
  const [state, setState] = useState<ChatInputState>("idle");

  return (
    <ChatInput
      state={state}
      value={value}
      onChange={(v) => {
        setValue(v);
        setState(v ? "typing" : "idle");
      }}
      onSubmit={async (v) => {
        setState("responding");
        await send(v);
        setState("resting");
      }}
      onStop={() => setState("resting")}
      placeholder="Ask me anything…"
    />
  );
}

The stylesheet import is required — the components are CSS Modules and the bundled sheet carries every class they reference.

Wiring it to your model

ChatInput renders one turn. useChatTurns owns the conversation — the turn list, the request in flight, and the reveal — and asks your app for the answers.

import { useChatTurns } from "inline-chat-kit";

const { turns, setDraft, submit, stop } = useChatTurns({
  onSend: async function* (message, { signal }) {
    const response = await fetch("/api/chat", {
      method: "POST",
      body: JSON.stringify({ message }),
      signal,
    });
    for await (const chunk of response.body!.pipeThrough(new TextDecoderStream())) {
      yield chunk;
    }
  },
});

onSend may return a string, a promise of one, or an async iterable of deltas. Return a string and the kit reveals it at a readable pace; return deltas and it shows them as they land. signal aborts when the reader presses stop.

The kit never invents an answer. There is no canned fallback anywhere in the package — if your handler returns nothing, nothing is what appears.

Rendering the turns

{turns.map((turn, i) => {
  const isActive = i === turns.length - 1 && (turn.state === "idle" || turn.state === "typing");
  return (
    <ChatTurnRow
      key={turn.id}
      turn={turn}
      isActiveInput={isActive}
      onDraft={setDraft}
      onSubmit={submit}
      onStop={stop}
      onEdit={beginEdit}
      onCancelEdit={cancelEdit}
    />
  );
})}

ChatTurnRow is already memoised, and that memo is load-bearing. The hook leaves untouched turns referentially identical when it rewrites one of them, but that only pays off if the rows act on it — otherwise every turn re-renders on every frame of every answer, and the cost grows with the conversation. Measured before the memo existed: streaming one answer produced 366 DOM mutations inside an unrelated, already-finished turn. With it, zero.

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

ChatInput is fully controlled. You own state and drive the whole choreography by moving between these values:

| state | What the input looks like | | --- | --- | | idle | Empty pill, placeholder showing | | typing | Text in the pill, send glyph revealed | | responding | Pill has become a glass bubble, glyph is a stop square | | resting | Settled bubble, hover actions available |

API

<ChatInput>

| Prop | Type | Notes | | --- | --- | --- | | state | ChatInputState | Required. See table above | | value | string | Required. Controlled value | | onChange | (value: string) => void | Required | | onSubmit | (value: string) => void | Required. Fires on Enter (Shift+Enter inserts a newline) | | onStop | () => void | Stop button while responding | | onAdd | () => void | The + button; opens the radial attachment fan | | onCopy | (value: string) => void | Hover action on a resting bubble | | onEdit | (value: string) => void | Hover action; put the turn back into typing | | onCancelEdit | () => void | Paired with isEditing | | isEditing | boolean | Shows save/cancel instead of send | | placeholder | string | | | animationConfig | InlineAnimConfig | Spring and stagger overrides — see below | | style | React.CSSProperties | |

ref exposes focus(), setValue(v) and getValue() via ChatInputHandle.

<ChatTurnRow>

One turn: the question as a composer that has become a bubble, and the answer beneath it. Not Message, because it is not one — the user half is a live input that morphs into its own bubble rather than a record of what was typed.

| Prop | Type | Default | Notes | | --- | --- | --- | --- | | turn | ChatTurn | | Required. Straight from useChatTurns | | isActiveInput | boolean | false | This row owns the live composer | | inputRef | Ref<ChatInputHandle> | null | For focus() | | placeholder | string | | | | animationConfig | InlineAnimConfig | | Passed to the input | | entranceDelay | number | 0 | Stagger, in seconds | | entrance | "rise" \| "fade" | "rise" | How the row arrives — a docked composer fades in place | | answerAfterTravel | boolean | false | The answer waits until the sent question has landed — docked, set by ChatExperience | | selectionMode | "marker" \| "precise" | "marker" | Passed to the highlighter | | questionAlign | "end" \| "stretch" | "end" | Where the composer sits — see below | | 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 | | | onHighlight | (turnId, text) => void | | A passage was marked | | onReplyInThread | (text, rect) => void | | Open a thread on the marked passage | | onBookmark | (turnId, text) => void | | Offers "Bookmark" in the highlight's menu; called again to take it back | | bookmarked | readonly string[] | | This turn's kept passages. Keep the array stable | | onRegenerate | (id) => void | | Draws the regenerate button | | 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 |

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 conversation off the bottom edge cannot tell the answer from the box you type in, and a washed-out composer reads as one you are not allowed to use. Lift it over the fade:

.feed [data-active-input] { position: relative; z-index: 6; }

questionAlign is end by default, because the composer is about to become the reader's own bubble and those sit right. stretch fills the row instead, which is what an opening composer wants: on an empty conversation it is not a message on its way, it is the box under the openers — and a pill floating at the right edge of a centred block reads as unrelated to the block.

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:

<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 on, a card is an opaque panel raised on it, and an inset is a row set into the card. --ick-ground, --ick-card, --ick-inset — a question group, a tool call and an approval all use the same three.

The card is paper and opaque, which matters more than it sounds: a translucent panel picks up whatever it is sitting on, which is how a tool call inside an approval came out pale green, back when the approval was tinted. In the dark the card is a lifted grey, because --ick-surface there is the page itself and a card painted with it would sink into the ground rather than sit on it — and that grey is mixed, not washed. It was nine percent white for a while, which looks identical on the page and olive over a tint. The rule held in the light, where the card is #fff, and was quietly false in the dark. An inset is mixed from the card for the same reason. A test now reads the values rather than the wiring: an alpha channel on either is the fault, whatever the number.

The ground stays a wash, deliberately. It is the bottom of the stack, so there is nothing under it to pick up but the page.

Stacked boxes are separated by surface and gap, not by a rule. A row is an inset panel with space around it, and nothing is underlined. A tool call used to draw a line under its header and a code block one under its label, which with two sections open made three stacked rules in a component the size of a paragraph — each saying again what the surface had already said.

All three steps, every time. A question is a group (ground) holding a card holding rows; a tool call is a ground holding a card holding its input and output; an approval is a ground holding a card holding what it is asking about. The tool used to be one box, and the box was the grey one — the same three surfaces stacked backwards, which on its own reads fine and beside a question card reads as a different system.

The approval had the same shape of fault from the other end: it was a tinted box and the only thing on paper was the tool call, so the title and the buttons sat straight on the ground. A question card puts its header and its Next button on the card, and this now does the same.

And the tint is gone, which is worth its own paragraph. An approval is a question — "may I run this" is the same species as "who else lives in the household": the assistant asking, blocking, with an answer. It should look like one. The tint was there on the reasoning that this is the one thing in an answer allowed to look like a box that stops you; the reasoning is real and colour was the wrong instrument. Everywhere else the marker is a small mark pointed at one thing and means this one — the badge on the option you picked, the stroke you drew, a citation, a source's number. A wash across a whole box meaning "this kind of box" is a second job for the one accent, and at 8% it was too weak to be an alarm and too strong to be nothing. In the dark it came out olive, which is not in the palette at all.

What says "this is unanswered" is that the box has buttons in it, and nothing else in a turn does. They leave when it settles, the way a question card's rows leave when it folds — and like a folded question, the approval keeps its paper and its shadow rather than changing into something else.

A component that is given a surface takes the next step down rather than repeating one. Inside an <Approval> the tool call is a row on its card — inset, at the row corner, no ground of its own and no shadow. Two grounds is one more than there is depth for, and so is two cards.

A rule down the side is a different device and stays: <Reasoning> uses one to mark an aside, and <ChainOfThought>'s says each step follows from the one above it.

Corners are concentric, on one chain. A box's corner is the corner of the thing inside it plus the gap between them, and there are four steps for the whole kit:

--ick-nest-inner   8    a badge, a chip, a fenced value
--ick-nest-row    16    an inset panel: an option, a field, a block of output
--ick-nest-card   24    paper, lifted off the ground
--ick-nest-ground 40    what the paper stands on

gaps: --ick-nest-pad 8 inside a card and a row, --ick-nest-ground-pad 16 around
      a card on its ground

Get it wrong and the two curves sit at different insets with the same radius, leaving a crescent between them — the thing that reads as "not quite fitting" without anybody being able to name it. It is written as calc() off a seed rather than as a list of numbers, so changing a padding moves the corners with it, and a test does the same sum for every nesting in the kit.

A component picks a step rather than deriving its own. Each used to derive: a tool call was a 6px block in a 14px card on a 22px ground, beside a question's 8 / 16 / 24 / 40. Both were internally concentric, and the two were nothing like each other — the same three surfaces at two scales, which reads as two systems rather than as one object holding different things. So a tool call and a question folded shut are now the same row, to the pixel: 40 tall, 16 in from the left, the glyph riding in the box a badge sits in. There is a story that stacks the two on one ground, and a test that compares every step of the two chains.

An answer's words start on the cards' edge. Everything in an answer's flow — the prose, the actions under it, <Reasoning>, <ChainOfThought>, <TaskList>, <Sources>, and a <SystemMessage> between turns — begins on --ick-answer-column, which is --ick-nest-ground-pad (16): the left edge of the white card of a tool call, an approval, a question or an artifact. The grey grounds hang that padding outside it, and a card's own words are indented inside the card the way a card's content always is. The prose ends on the mirror of it, so on a phone it stops at the card's right edge too. A host card in turn.parts, or hand-written prose beside the kit's, lines up by reading the same token.

A short box takes the corner it can. A row folded shut is 40px tall and a 24px corner on it clamps to a pill — both of them, equally, which is the point.

A <CodeBlock> reads --ick-code-radius, so a box that nests one repoints it at the step its own corner implies — the way <Tool> hands it the row's. It reads --ick-code-pad the same way, for its inner padding: <Tool> takes that down to 8 so a panel's label lands on the column its header's glyph is in, and every section of a tool call — code or text — starts on that one column.

<Tool>

One tool call on the way to an answer: what was run, what with, what came back.

<Tool
  name="search_web"
  state="done"
  summary="3 results"
  duration={412}
  input={{ query: "weather in Belgrade", limit: 3 }}
  output={results}
/>

| Prop | Type | Notes | | --- | --- | --- | | name | string | Set in mono: it is an identifier, not prose | | state | "pending" \| "running" \| "done" \| "error" | Default "done" | | summary | ReactNode | A sentence for what it did | | input / output | unknown | See below | | error | ReactNode | Drawn instead of the output | | duration | number | In ms. Shown once it has finished | | open / defaultOpen / onOpenChange | | Controlled or not | | labels | Partial<Record<…, string>> | input, output, error, and a word per state |

Shut by default, because most of the time nobody cares — and open when it failed, because an error nobody can see has not been reported. That is derived from the state rather than forced by an effect, so a call that fails later opens itself, while one somebody deliberately shut stays shut.

What you give it decides how it is drawn. A string is text — wrapping "Belgrade, 24°C" in a fence puts it in quotes with its newlines spelled out, which is worse than reading it. An object is JSON, in a CodeBlock with its copy button. An element is left alone, so anything you want drawn some other way you draw yourself.

The state is never carried by colour alone: the glyph changes shape, and the row says which state it is in in words only a screen reader hears.

What a turn carries: TurnPart

An answer used to be one string, and everything the agent tier draws had nowhere to live. A turn now carries parts alongside ai, and a SendHandler streams them in among the prose:

const send: SendHandler = async function* (message) {
  yield { kind: "reasoning", id: "r", text: "Two numbers matter here.", state: "thinking" };
  yield { kind: "tool", id: "t", name: "search_web", state: "running", input: { query } };
  yield { kind: "tool", id: "t", name: "search_web", state: "done", output, duration: 412 };
  yield { kind: "reasoning", id: "r", state: "done" };
  yield "The Higgs weighs about 125 GeV.";   // a delta of the answer's prose
};

A streamed item is either a string — appended to ai, as before — or a TurnPart, merged into turn.parts by its id. The merge is shallow and that is the point: send the state change on its own and the text that arrived before it is still there. <ChatTurnRow> draws each kind with the component that owns it.

| kind | Drawn as | Carries | | --- | --- | --- | | reasoning | <Reasoning> | text, state, duration | | tool | <Tool> | name, state, summary, input, output, error, duration | | tasks | <TaskList> | title, tasks, collapsible | | chain | <ChainOfThought> | steps, state, duration | | sources | <Sources> | sources, title, collapsible | | 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.

Where a part sits in the prose

The answer is drawn in the order the stream sent it. A part remembers how much prose had arrived when it did — at, in characters of ai — and is drawn at that point, so a sentence that introduces a card comes before the card:

yield "I suggest this change:";                                   // prose
yield { kind: "custom", id: "change", type: "plan-diff", data };  // at: 22
yield " Tell me if it looks right.";                              // prose, after the card

useChatTurns stamps at on a part's first appearance and nothing moves it afterwards: an update to a part is not a new part, and a card a host adds with updatePart after the answer lands at the end. Give at yourself to place a part — at: 0 puts it before all the prose. A part with no at sits before the prose, which is where every part sat before this existed, so turns built by hand look as they always have.

The prose is still one string: ai is what Copy copies, what a screen reader hears and what a version keeps. Only the drawing is cut, at the points the parts arrived — each run is its own block of markdown, and a highlight cannot cross a card. The row of actions goes after whatever the answer ends with, so an answer made only of parts has one too, without a Copy of nothing.

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.

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.

Citing a source from the prose

[^1] in the answer is a citation marker, and the number is a position in the turn's sources part:

yield { kind: "sources", id: "s", sources: [atlas, pdg] };
yield "The combined figure is 125.25 GeV[^1], to a fifth of a percent[^2].";

It draws as an <InlineCitation> carrying the source's title, and the marker is left out of the tokens — so a highlight drawn across the sentence, and the text a thread quotes back, do not contain a stray [1].

This is the kit's one extension to the markdown grammar. GFM spells footnotes the same way but wants a [^1]: … definition in the document; a model streams the marker and sends the list beside the text, never below it. Without it a citation could only be written by hand in JSX — which a stream cannot do, so the component existed and no real conversation could reach it.

Send the list before the prose that cites it. Sent after, the markers draw bare and fill in later, which works and looks like a bug.

A question is answered by the person reading it, not by the stream — so useChatTurns also returns updatePart(turnId, part), and ChatTurnRow reports through onAnswerQuestion / onEditQuestion. The row never keeps the answer; the parts are yours.

Parts are cleared when a turn is answered again: the tool calls that produced the old answer are not evidence for the new one.

One header for everything that folds

<Tool>, <Reasoning>, <ChainOfThought>, <TaskList> and <Sources> all open the same way, so they share DisclosureHeader and DisclosureBody — internals, not exports. The header owns the button-or-heading switch, the aria-expanded / aria-controls wiring, the chevron, the shimmer under a pending label, and the guard that stops a click on the row from starting a marker on the highlighter underneath. The body owns the always-present container and the height reveal.

Two fits, and the difference is real rather than decorative:

| | Fit | Why | | --- | --- | --- | | Tool, TaskList, Sources | band | A full-width row. It has a right edge, so the meta and the chevron are pushed to it. | | Reasoning, ChainOfThought | inline | A label that hugs its own words. These sit in the flow of an answer as asides; a chevron pushed to a right edge 500px away floats alone in white space. |

A component that means something different by its label repoints a token from its own root rather than passing a class in — two .label rules from two stylesheets have equal specificity, and which one wins is import order. --ick-disclosure-label, -font, -weight, -size, -glyph, -meta.

<QuestionGroup> folds too and does not use this, for a reason worth stating: its shut state is a card, and opening it is a FLIP morph between two layouts rather than a box growing from zero height under a row. A test holds that exemption, and the exemption stays honest — the day it stops being a morph, it owes an answer.

<Reasoning>

What the model worked through before it answered.

<Reasoning state={thinking ? "thinking" : "done"}>{thoughts}</Reasoning>

| Prop | Type | Notes | | --- | --- | --- | | children | ReactNode | The thinking. Prose — see Tool for structure | | state | "thinking" \| "done" | Default "done" | | duration | number | In ms. Left out, the block times itself | | open / defaultOpen / onOpenChange | | Controlled or not | | labels | Partial<Record<…, string>> | thinking, thought, thoughtFor |

Open while it thinks, folded away once the answer starts. That is the one detail every kit shipping this has converged on, and it is right: thinking is worth watching while it happens and worth almost nothing afterwards — but it has to stay reachable, because the times it matters are exactly the times the answer looks wrong.

Folding is the block's preference, not something done to the reader. Open it and it stays open, however many times the state changes underneath.

Without a duration it times itself, from the moment it starts thinking to the moment it stops. Pass one when you already know — replaying a transcript, where the thinking did not happen just now.

While it thinks the word shimmers, which is how this kit says "provisional" everywhere. It is a real word in the button rather than a <Loader>: the loader is decorative and marks itself aria-hidden, and hiding this one would leave a control with nothing to call it.

<Context>

How full the context window is.

<ChatHeader title="Higgs boson" subtitle="14 turns">
  <Context used={840_000} total={1_000_000} label={false} />
</ChatHeader>

| Prop | Type | Notes | | --- | --- | --- | | used / total | number | In tokens, or whatever unit you count in | | warnAt | number | Fraction. Default 0.8 | | label | ReactNode \| false | The percentage by default; false for the ring alone | | labels | Partial<Record<…, string>> | name, of, tokens, nearlyFull |

Small on purpose. It is a gauge, not a feature, and it earns its place for one reason: it is the only honest way to explain why a long conversation starts forgetting. Without it the forgetting looks like the model being stupid rather than the window being full.

Which is why the warning says what happens next rather than only that a number is high — "82%" tells somebody nothing they can act on. The whole sentence is the meter's accessible name and its title, so it reaches a pointer and a screen reader alike.

Two colours, not three: quiet until warnAt, then the danger colour. A gauge with an amber in the middle makes somebody learn a scale to read a number they can already see.

<Approval>

"It wants to do this. Is that all right?"

<Approval
  title="Run a command in your shell"
  description="It removes the generated screenshots. Nothing else is touched."
  decision={decision}
  onDecide={setDecision}
>
  <Tool name="bash" state="pending" input={{ command: "rm -rf Shots/" }} defaultOpen />
</Approval>

| Prop | Type | Notes | | --- | --- | --- | | title | ReactNode | What is being asked. Names the region | | description | ReactNode | Why, or what it will touch | | children | ReactNode | The thing itself — usually a <Tool> or a <CodeBlock> | | 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 the primary: the narrow permission is the one that should be easiest to give, and the standing one should cost a moment's thought. Deny sits alone on the left with the two that say yes pushed right — a destructive choice flush against an affirmative one is a mis-click waiting to happen — and it is first in the DOM 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.

<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.

Decided, it stops being a set of buttons and becomes a record of what was 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?, 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.

<Sources> and <InlineCitation>

A numbered marker in the text, and the list underneath.

<p>
  The Higgs is a point particle, so{" "}
  <InlineCitation index={1} source={sources[0]} onSelect={(_, s) => setActive(s.id)}>
    it has no measurable spatial extent
  </InlineCitation>.
</p>
<Sources sources={sources} activeId={active} />

| Sources | Type | Notes | | --- | --- | --- | | sources | Source[] | { id, title, url?, origin?, quote? } | | title | ReactNode | Defaults to labels.title | | collapsible | boolean | false | | activeId | string \| null | The one arrived at from a marker | | onSelect | (source, index) => void | |

| InlineCitation | Type | Notes | | --- | --- | --- | | index | number | 1-based, and it has to match the entry's place | | source | Source | Named in the marker's accessible name | | children | ReactNode | The passage this citation speaks for — marked, if given | | onSelect | (index, source?) => void | Without one the marker is not a control |

The citation marker and the highlight marker are the same interaction seen twice. The kit already had a way of saying this run of words is picked out — the marker somebody draws over an answer to ask about it. A citation is that same statement made by the answer rather than by the reader, so it is drawn the same way rather than in a second visual language nobody has learned. Give InlineCitation the passage as children and the passage is marked; give it none and the marker stands on its own after whatever precedes it.

Pressing a marker marks the entry it points at rather than scrolling to it. The list is already under the answer, and moving the page under somebody who clicked a marker in a sentence they were reading loses them the sentence.

The list is open by default. Sources are the difference between an answer somebody can check and one they have to trust, and folding that away by default says the opposite of what a citation is for.

<ChainOfThought>

How the answer was arrived at, step by step.

<ChainOfThought
  state={thinking ? "thinking" : "done"}
  duration={4200}
  steps={[
    { id: "a", label: "The question is about size, not mass", body: "A point particle has none." },
    { id: "b", label: "Checked the measured value", body: <Tool name="search_web" … /> },
  ]}
/>

| Prop | Type | Notes | | --- | --- | --- | | steps | Thought[] | { id, label, body?, state? } | | state | "thinking" \| "done" | thinking holds it open and narrates the running step | | duration | number | In ms, for the whole chain | | open / defaultOpen / onOpenChange | | Controlled or not | | labels | Partial<Record<…, string>> | through, step, steps, thinking |

Three components in this kit draw a sequence, and the line between them is the only reason there are three:

| | What it is | Shape | | --- | --- | --- | | Reasoning | The model talking to itself | Prose, unstructured | | TaskList | A plan | Known up front, fixed order, items change state | | ChainOfThought | A derivation | Grows; each step follows from the one above |

That last word is what the line down the glyph column draws. A task list has no line between its items, because a plan's items do not follow from each other — they are a set, in an order somebody chose.

A step's body is whatever you put there: prose, or a <Tool> if the step was a tool call. While the chain is thinking its header carries the running step's label rather than a count — that is the question somebody watching is asking, and the reason to look at a folded chain at all.

<TaskList>

What the agent means to do, what it is doing, and what it has finished.

<TaskList
  title="Plan"
  collapsible
  tasks={[
    { id: "read", label: "Read the care plan", state: "done", detail: "42 lines" },
    { id: "gaps", label: "Find the gaps in the weekly cover", state: "running" },
    { id: "draft", label: "Draft the questions for the family" },
  ]}
/>

| Prop | Type | Notes | | --- | --- | --- | | tasks | Task[] | { id, label, state?, detail? } | | title | ReactNode | Gives it a row to fold into. Without one there is no row | | collapsible | boolean | false | | open / defaultOpen / onOpenChange | | Controlled or not | | labels | Partial<Record<…, string>> | The four states, and progress ("{done} of {total}") |

A task is pending, running, done or error — the same four as a tool call, and the same glyphs, because they are the same four states and naming them differently in two places buys nothing.

The order never changes. A list that sorted itself as work progressed would move the line somebody is reading out from under them, and the sequence is half of what the list is saying — these steps, in this order. Only the glyphs change.

collapsible folds it away once every task is done: a plan is worth watching while it runs and worth little afterwards. Anybody reading it can overrule that, in either direction, for good.

The one being worked on carries aria-current="step", so a screen reader can jump to "where is it up to" rather than counting down the list.

<QuestionCard> and <QuestionGroup>

A structured question inside a conversation: the assistant asks something with a shape to it, and the answer is picked or typed rather than written out.

<QuestionGroup
  id="about-them"
  title="Setting up the run"
  questions={questions}
  answers={answers}
  activeIndex={activeIndex}
  collapsible={done && questions.length >= FOLDABLE_FROM}
  onCommit={(id, answer) => setAnswers((all) => ({ ...all, [id]: answer }))}
  onEdit={setEditing}
/>

A Question is one of three shapes — inputs (type something), single (pick one), multi (pick several, optionally with a "something else" field). Each carries a shortTitle, which is what it is called once it folds into a row.

A card is in one of three states, and morphs between them:

| state | what it is | | --- | --- | | upcoming | one dim row, waiting its turn | | active | the question, open, being answered | | collapsed | one row: the short title, the answer as chips, and a way back in |

QuestionGroup holds a step's worth. title names the step, at the top, and is also the fold control when there is one — which is the point of putting it there. A control at the top does not move when the body under it changes, so folding stops being two shapes swapping places and becomes one header with two bodies. Left out on a foldable group, the count stands in so the control still has a name; left out on one that cannot fold, there is no header at all.

Folded, the body is a single summary row — not a peek at the list, because a peek costs more height than the answers it shows.

Two decisions carried over from the original, both worth keeping: single waits a beat after a choice before committing, or the card is gone before anyone sees what they picked; and the "something else" row is a <label>, not a button, because an input inside a button is not reliably focusable.

Two changed. The collapsed row is a single <button> naming what it does ("Edit answer: Household") rather than a click handler on a <div> with another button inside it — that could be clicked but not tabbed to. And the letter badges are aria-hidden: the letter is a visual index, and left in the tree it turns a field called "Their name" into one called "a Their name".

Composing a fourth kind of question

Three shapes are not the only three. The parts a card is built from are exported, so a shape the kit does not ship is a composition rather than a fork — and it arrives already wearing the same tokens, focus behaviour and ARIA as the ones that do.

<QuestionShell
  number={3}
  title="How soon do they need this?"
  subtitle="Roughly is fine"
  footer={<Button variant="secondary" size="m" onClick={commit}>Next</Button>}
>
  {levels.map((level, i) => (
    <QuestionOptionRow
      key={level.id}
      letter={"abc"[i]}
      title={level.title}
      description={level.description}
      selected={picked === level.id}
      onClick={() => setPicked(level.id)}
    />
  ))}
  <QuestionFieldRow
    letter="d"
    label="Anything we should know"
    value={note}
    onChange={setNote}
  />
</QuestionShell>

| Part | What it is | | --- | --- | | QuestionShell | The card: header, the column the rows sit in, a right-aligned footer | | QuestionOptionRow | A row that picks. A <button> with aria-pressed | | QuestionFieldRow | A row that is typed into. A <label>, so the whole row focuses the input | | QuestionOtherRow | The "something else" row: reads as an option, is a text field | | QuestionBadge | The 24px square with the letter or the number |

Each takes a className that is added to its own rather than replacing it, spreads the rest of its props onto the element it ends in, and forwards its ref to the thing worth having one for — the input, in the two rows that have one. On the two rows that take one, className styles the row and everything else goes to the input.

QuestionShell paints the card — background, radius, shadow — unless you pass card={false}, which is what QuestionCard does: the box that morphs between the three states is its own, and two would nest.

letter is optional on all three rows. Left out, the row starts at its title. onEnter fires on Enter unless your own onKeyDown called preventDefault first, which is how a handler says it has dealt with the key.

<EmptyState> and <Loader>

The two ends of a conversation that has not happened yet: what is on screen before anybody asks, and the gap between sending and the first word.

| EmptyState | Type | Notes | | --- | --- | --- | | icon / title / description | ReactNode | Each optional; nothing is drawn in place of what you leave out | | suggestions | string[] | Openers | | onSuggestion | (text: string) => void | Without it, no openers are drawn | | suggestionsLabel | string | Names the group. Default "Suggestions" |

title renders as text, not a heading. This sits inside a conversation the host already owns, and claiming a level in their document is not ours to do — pass <h2>…</h2> if it should be one.

| Loader | Type | Notes | | --- | --- | --- | | variant | "dots" \| "shimmer" | Default "dots" | | children | ReactNode | The words the shimmer runs through | | label | string \| null | Default null — see below |

The loader is silent by default. useChatTurns already announces that a response is coming, and a second live region saying the same thing means hearing it twice. Pass label only when nothing else is speaking for you.

ChatTurnRow shows it between the question being sent and the first word landing, so a sent question is never a blank space.

<AnswerActions>

Copy, regenerate and a verdict, under a settled answer. ChatTurnRow renders it for you; it is exported for anyone composing their own row.

| Prop | Type | Default | Notes | | --- | --- | --- | --- | | text | string | | Required. What copy takes | | onCopy | (text: string) => void | writes to the clipboard | | | onRegenerate | () => void | | Omit and the button is not drawn | | onFeedback | (verdict: "up" \| "down" \| null) => void | | Omit and the thumbs are not drawn | | feedback | "up" \| "down" \| null | null | Controlled | | busy | boolean | false | While regenerating | | reveal | boolean | false | Invisible until hovered or focused | | labels | Partial<Record<…, string>> | | | | children | ReactNode | | Your own controls, after the built-in ones |

Only what has somewhere to report is drawn: no onRegenerate, no regenerate button. A control that calls nothing looks like a feature and behaves like a dead end.

Pressing the verdict already given reports null — that is how somebody takes it back.

Inside a turn they appear when the answer settles. Offering to copy a half-written answer, or to rate one, is offering the wrong thing.

<Conversation>

The scroll container. It keeps up with an answer as it arrives and stops the instant the reader scrolls away, with a button offering the way back.

<Conversation>
  {turns.map((turn) => <ChatTurnRow key={turn.id} turn={turn} … />)}
</Conversation>

| Prop | Type | Default | Notes | | --- | --- | --- | --- | | anchorId | string | | Hold this element at the top instead of following the end | | anchorOffset | number | 0 | How far below the top edge it sits — leave room for a fixed header | | threshold | number | 64 | How close still counts as following | | 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 | | className | string | | Goes on the root, which is the box you lay out | | viewportClassName | string | | Goes on the element that scrolls — padding belongs here |

ref is forwarded to the viewport, not the root: anyone reaching for a ref here wants to scroll something, and the root does not scroll.

Three things worth knowing.

anchorId is the one that changes the feel. Without it the view follows the end of the content, which is what a chat that stacks downwards wants. With it, the named element is brought to the top and held there while the answer grows underneath — so a reader sees their question and its answer, and not the whole conversation pushed up from below with the composer ending past the fold. Point it at the turn that was just submitted:

const [anchor, setAnchor] = useState<string | null>(null);
const send = (id: string, value: string) => { setAnchor(id); submit(id, value); };

<Conversation anchorId={anchor ? `turn-${anchor}` : undefined} anchorOffset={100}>

This needs room to scroll into — an element cannot be brought to the top of a container that ends just below it. A large padding-bottom on the viewport is what provides it.

Without an anchor it follows the end of the content, not the bottom of the container, and those are only the same when nothing is padded below. A chat with a screen-height pad beneath it would otherwise scroll the answer off the screen to sit in front of a blank space.

And it reads the reader's intent from the input, not from the scroll event. A component that watches scrolling cannot tell its own from theirs, and ends up either dragging them back down mid-sentence or never following at all. A wheel upwards, a page key, a drag away from the end: any of those and it lets go.

<ArtifactCard>, <ArtifactPane>, <ChatLayout>, useArtifacts

What the answer produced, when it is bigger than the answer — a plan, a document, a file. Three pieces and one decision.

const artifacts = useArtifacts();

<ChatLayout
  pane={({ narrow }) =>
    artifacts.openId ? (
      <ArtifactPane title="5k training plan" meta="8 weeks" modal={narrow} onClose={artifacts.close}>
        <YourPlan />
      </ArtifactPane>
    ) : null
  }
>
  <Conversation>
    <ChatTurnRow turn={turn} openArtifactId={artifacts.openId} onOpenArtifact={(_, id) => artifacts.toggle(id)} />
  </Conversation>
</ChatLayout>

The kit decides where the pane goes. On the right, with the conversation making room; below <ChatLayout>'s width it covers the conversation instead. A preview pane is one of the few patterns every AI chat now has, and the worth of a pattern is that it is the same every time — ask for a plan, get a card, press it, the plan opens on the right. A kit that let each host place it would be shipping four chats that behave differently and calling it flexibility.

The kit does not decide what is in it. <ArtifactPane> takes children: a plan, a table, a document, a diagram. That is the part that actually differs between products, and the only part.

| Prop | Type | Notes | | --- | --- | --- | | <ArtifactCard> id | string | What the pane opens. The card and the pane share nothing else | | title, meta | ReactNode | | | kind | "code" \| "text" | How the preview is drawn | | content | string | Absent while it is being written, which is how one usually arrives | | lines | number | How much shows before the cut. Default 8 | | open | boolean | True while its pane is the one on screen | | 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 be held inside it and Escape has to close it, because there is nothing usable behind it. Beside the conversation both would be wrong — trapping focus would lock a reader out of the chat they are still reading. <ChatLayout> sets it from its own width, so you only pass it yourself if you are placing the pane without one.

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:

<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:

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.

<SystemMessage>The oldest messages are dropping out of the window.</SystemMessage>
<SystemMessage tone="danger">Lost the connection. Nothing since your last message was saved.</SystemMessage>

| Prop | Type | Notes | | --- | --- | --- | | children | ReactNode | The sentence. Say what happens next, not that a state changed | | tone | "notice" \| "danger" | Two, because <Context> already settled that three is one too many |

Reachable from a stream as well, as a part of kind notice, which is the only way anything gets into a conversation without the host placing it by hand.

It has no icon, and that is the component rather than an omission from it. Every picture in this kit carries a state the words beside it also carry — queued, running, failed, allowed — so a reader the picture does not reach loses nothing. An icon here would say "something is being announced" beside a sentence announcing it.

No dismiss and no action. It is a line of the transcript, not a toast: dismissing one would be editing what happened. A host that wants a button under it composes one, which costs them a line and costs this component an API.

No live region. The kit has one — see announce — written to on a later tick. A second one says everything twice, which is the fault that region exists to have fixed. A host streaming a notice should announce it.

<Branch>

Which answer you are looking at, and how to reach the others.

<Branch total={turn.versions?.length ?? 0} index={turn.versionIndex ?? 0} onSelect={show} />

| Prop | Type | Notes | | --- | --- | --- | | total | number | How many answers this turn has had | | index | number | Which is on screen, from zero. Out of range is clamped | | onSelect | (index: number) => void | | | labels | Partial<{ previous, next, position }> | position fills in {index} and {total} |

It draws nothing at all when total is under two. A control reading "1 of 1" offers to take you nowhere, so a turn answered once looks exactly as it did before there were versions.

Regenerating keeps the old answer. It used to overwrite ai and parts, which threw away the answer being compared against — and comparing is the only reason to press regenerate. A turn now carries versions: TurnVersion[] and versionIndex, useChatTurns returns showVersion(id, index), and <ChatTurnRow> draws the control beside the answer actions when you give it onShowVersion.

ai and parts stay what they were — the answer on screen. They are kept equal to versions[versionIndex] by one function that both writers (the batched stream flush and the turn patcher) go through; two writers for one fact is how they drift, and a test compares them after a stream.

Both fields are optional, so a turn a host built by hand still renders — the same tolerance parts has.

<Attachments>

What goes along with a message.

<Attachments attachments={files} onRemove={(id) => drop(id)} />

| Prop | Type | Notes | | --- | --- | --- | | attachments | Attachment[] | Required. Nothing to show draws nothing at all | | onRemove | (id: string) => void | Leave it out and they are a record rather than a control | | labels | Partial<{ remove }> | |

An Attachment is { id, name, url?, type?, size? }. An image with a url shows itself; everything else shows a glyph, its name and its size — a thumbnail of a PDF at 64px is a grey rectangle with a corner turned down and tells you less than the filename does.

The same row draws them in the composer and under the message once it has been sent. onRemove is the whole difference between a control and a record, and <ChatInput> stops passing one the moment the message goes.

In the composer. <ChatInput> opens the picker from its + and keeps what comes back, unless you take over:

| Prop | Type | Notes | | --- | --- | --- | | attachments | Attachment[] | Controlled. Left out, the composer keeps its own | | onAttach | (files: File[]) => void | Given, the composer hands the files over instead of attaching them — for uploading first and attaching the URL you get back | | onRemoveAttachment | (id: string) => void | | | accept | string | Passed to the picker. Defaults to image/* | | multiple | boolean | Off |

onSubmit is (value, attachments). That second argument is the point: before it, a file could be picked, shown in the composer, and then quietly dropped on send — the message went and the picture did not, which is worse than not offering the button. A picture on its own is a message, so an empty box with something attached still sends.

The object URLs the composer makes are revoked — when one is removed, when one replaces another, and on unmount. createObjectURL pins the file in memory until it is; nothing was revoking, so attaching and removing ten times leaked ten of them.

They arrive at your SendHandler on the context: (message, { signal, turnId, attachments }). And they live on the turn as turn.attachments, which is what <ChatTurnRow> hands back to the composer so a sent message still shows what went with it.

<CodeBlock>

A fenced block: the language, a copy button, and code that scrolls sideways rather than widening the answer. The markdown renderer uses it for every fence, and it is exported for use on its own.

| Prop | Type | Default | Notes | | --- | --- | --- | --- | | code | string | | Required | | lang | string | | The fence's language. Unknown ones render unhighlighted | | label | string \| false | the language | false drops the caption | | copyable | boolean | true | false with label={false} removes the bar entirely | | onCopy | (code: string) => void | writes to the clipboard | | | copiedFor | number | 1600 | How long the button stays confirmed, in ms |

Eleven languages are registered: TypeScript, JavaScript, HTML/XML, CSS, JSON, YAML, Bash, Python, SQL, Markdown and diff — plus the aliases people actually type (ts, tsx, js, sh, py, yml, …). lowlight/common is 37 languages and 51.6 KB gzipped; these cost half of that and cover what a chat actually shows. A language outside the list renders unhighlighted rather than throwing.

And they are not in your bundle until something needs them. The grammars are a 25 kB gzip chunk behind a dynamic import() — most conversations never show a fence, and 25 kB is 42% of what the package used to weigh. The first block on a page paints its code plain and colours in when the chunk lands; every block after that is coloured on its first paint, because the loaded highlighter is kept. There is no layout shift either way: the text is the same, only the colour arrives late.

If that trade is wrong for you — a docs tool where every answer is code — import { loadHighlighter } from "inline-chat-kit" and call it once at start-up. It is idempotent and concurrent callers share the one fetch. canHighlight(lang) answers whether a language is one of the eleven without loading anything, for a caller deciding what to draw.

The scheme is ink at four weights rather than a syntax palette — this kit is ink, paper and one acid yellow, and twelve colours dropped into it read as somebody else's component. Six tokens (--ick-code-keyword, -string, -comment, -name, -number, -attr) turn it into whatever palette you already own.

A block is not markable. Preformatted text split into word tokens stops being preformatted, so the highlighter skips it; copy is what people want from code anyway.

<ChatHeader>

The chrome above the conversation: who you are talking to, what about, and the handful of things you can do to the whole thread.

<ChatHeader
  title={firstQuestion}
  subtitle="Claude Opus 5"
  backHref="/"
  actions={[
    { id: "bookmarks", label: "Saved highlights", icon: <Bookmark size={16} />, count: 3, pinned: true },
    { id: "share", label: "Share", icon: <Share2 size={16} />, onClick: share },
  ]}
>
  <YourModelPicker />
</ChatHeader>

| Prop | Type | Default | Notes | | --- | --- | --- | --- | | title | ReactNode | | What the conversation is about | | subtitle | ReactNode | | Second line — the model, a count, a state | | avatar | ReactNode | | Drawn before the title | | headingLevel | 1–6 | false | 2 | The level belongs to your document | | truncate | boolean | true | Long titles get an ellipsis, not a second line | | onBack | () => void | | Renders a back button | | backHref | string | | Renders a back link instead | | backLabel | string | "Back" | | | actions | ChatHeaderAction[] | [] | The managed actions. These are what collapse | | overflowLabel | string | "More actions" | | | variant | "plain" \| "glass" \| "bordered" | "plain" | | | size | "s" \| "m" \| "l" | "m" | 40 / 48 / 56px | | align | "start" \| "center" | "start" | center is the native arrangement | | sticky | boolean | false | | | elevateOnScroll | boolean | sticky | Border and backdrop appear once content scrolls under | | collapseActionsAt | number \| false | 520 | Header width, not viewport width | | landmark | boolean | true | false inside a panel, where banner would be a lie | | children | ReactNode | | Anything the kit should not manage. Never collapses |

Each action is { id, label, icon, onClick?, href?, count?, active?, disabled?, pinned?, variant? }. variant is how one action stands out — "primary" for the host's own — and only applies while it is in the header rather than folded into the menu