inline-chat-kit 0.49.0

package/dist/markdown/parse.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Markdown, parsed here rather than by `unified` + `remark`.
+ *
+ * That pipeline was 31.6 KB gzip — a third of the whole package — and the
+ * slowest thing in it: 0.9ms per thousand characters, 8.9ms at ten thousand,
+ * which is half a frame spent re-parsing an answer that grew by one word.
+ *
+ * The kit uses a thin slice of it. `parseMarkdown` walks the tree straight
+ * into a flat token list and a handful of elements, and it touches nine block
+ * types and nine inline ones. This produces exactly those, in the same shape,
+ * so nothing downstream changed.
+ *
+ * **It is not a CommonMark implementation and does not try to be.** It handles
+ * what a model actually writes. Where it diverges from `remark` the difference
+ * is caught rather than assumed: `remark` stays a dev dependency and a test
+ * parses a corpus through both and compares the finished documents.
+ */
+export type Phrasing = {
+    type: "text";
+    value: string;
+} | {
+    type: "strong";
+    children: Phrasing[];
+} | {
+    type: "emphasis";
+    children: Phrasing[];
+} | {
+    type: "delete";
+    children: Phrasing[];
+} | {
+    type: "inlineCode";
+    value: string;
+} | {
+    type: "link";
+    url: string;
+    title?: string;
+    children: Phrasing[];
+} | {
+    type: "image";
+    url: string;
+    alt: string;
+}
+/**
+ * `[^1]` — a citation marker, pointing at the nth source of the turn.
+ *
+ * The kit's one extension to the grammar, and the only place this parser
+ * deliberately reads something `remark` does not. GFM spells footnotes the
+ * same way but needs a `[^1]: …` definition somewhere in the document to
+ * make one; a model streaming an answer emits the marker and sends the
+ * sources beside the text, never below it. Without this an `InlineCitation`
+ * can only be written by hand in JSX, which a stream cannot do — so the
+ * component existed and nothing in a real conversation could reach it. */
+ | {
+    type: "citation";
+    index: number;
+} | {
+    type: "break";
+}
+/** Recognised so it can be dropped, which is what the renderer does with it. */
+ | {
+    type: "html";
+    value: string;
+};
+export interface ListItem {
+    type: "listItem";
+    children: Block[];
+}
+export interface TableCell {
+    type: "tableCell";
+    children: Phrasing[];
+}
+export interface TableRow {
+    type: "tableRow";
+    children: TableCell[];
+}
+export type Block = {
+    type: "paragraph";
+    children: Phrasing[];
+} | {
+    type: "heading";
+    depth: number;
+    children: Phrasing[];
+} | {
+    type: "list";
+    ordered: boolean;
+    start?: number;
+    children: ListItem[];
+} | {
+    type: "blockquote";
+    children: Block[];
+} | {
+    type: "code";
+    lang?: string;
+    value: string;
+} | {
+    type: "thematicBreak";
+} | {
+    type: "table";
+    children: TableRow[];
+} | {
+    type: "html";
+    value: string;
+};
+export declare function parseInline(src: string): Phrasing[];
+export declare function parseBlocks(src: string): Block[];

package/dist/markdown/parseMarkdown.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Markdown, in the one shape the highlighter can work with.
+ *
+ * The highlighter's whole model is a **flat array of word and space tokens**,
+ * addressed by index. Hit-testing reads `data-index` off whatever is under the
+ * pointer; the keyboard cursor walks the indices; the text of a highlight is
+ * rebuilt by joining a run of them. Markdown is a tree, and the obvious move —
+ * render markdown and highlight the result — breaks every one of those.
+ *
+ * So the tree and the indices are separated. Parsing produces both:
+ *
+ *   - `tokens`, still flat, still in reading order, exactly as before
+ *   - `nodes`, a small tree that says where each token sits
+ *
+ * Nothing downstream changes. A stroke across `**bold**` is a run of indices
+ * like any other, even though the words live in different elements.
+ */
+export type MdNode = 
+/** One entry of `tokens`, by index. */
+{
+    type: "token";
+    index: number;
+} | {
+    type: "el";
+    tag: string;
+    props?: Record<string, string>;
+    children: MdNode[];
+}
+/** A fenced block. Preformatted, so it is not tokenised — see below. */
+ | {
+    type: "code";
+    lang?: string;
+    value: string;
+};
+export interface MarkdownDoc {
+    /** Flat, in reading order. The bridge to every existing mechanism. */
+    tokens: string[];
+    nodes: MdNode[];
+}
+/**
+ * Parse once per distinct string.
+ *
+ * Called from a `useMemo` keyed on the text, which during streaming still
+ * means once per frame — the text is different every frame. That is measured
+ * rather than assumed; see the note in `TextHighlighter`.
+ */
+export declare function parseMarkdown(text: string): MarkdownDoc;

package/dist/radiusCorrection/useCorrectedRadius.d.ts

@@ -0,0 +1,24 @@
+import { RefObject } from 'react';
+/**
+ * A box's corner in pixels, so Motion can keep it round while it scales it.
+ *
+ * A `layout` animation does not resize a box — it **scales** one, and a browser
+ * scaling a box scales the corner with it. Measured on the question group
+ * opening a card: `scaleY` runs from 0.932 to 1 while `border-radius` stays a
+ * flat 40px, which paints a 40 × 37 ellipse and eases back to a circle. That is
+ * the stretching and squashing everyone can see and nobody can name.
+ *
+ * Motion has a corrector for exactly this — it rewrites the radius as
+ * `x% y%` against the projected box every frame — but it only runs on values
+ * **Motion is managing**. A radius that lives in a CSS class is invisible to
+ * it, so the whole morph goes uncorrected.
+ *
+ * So the number is read off the element and handed back through `style`, where
+ * Motion can see it. Read rather than hard-coded, because the corner is a
+ * token and a host may retune it; `var(--…)` is no use here, since the
+ * corrector parses pixels and returns anything else untouched.
+ *
+ * `undefined` until the element exists, which is one render with the class's
+ * own corner and no animation running yet — nothing to see.
+ */
+export declare function useCorrectedRadius(ref: RefObject<HTMLElement | null>): number | undefined;

package/dist/reducedMotion/reducedMotion.d.ts

@@ -0,0 +1,3 @@
+export declare function prefersReducedMotion(): boolean;
+/** For tests, which change what `matchMedia` returns between cases. */
+export declare function resetReducedMotionCache(): void;

package/dist/stateGlyph/StateGlyph.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Queued, working, finished, failed.
+ *
+ * One vocabulary across the kit rather than one per component — a tool call
+ * and a task in a list are in the same four states, and calling the third one
+ * `active` in one place and `running` in another buys nothing and costs a
+ * mental translation every time somebody reads both.
+ */
+export type WorkState = "pending" | "running" | "done" | "error";
+/**
+ * The 16px square that says which of the four states something is in.
+ *
+ * Four shapes, not four colours. Colour is the second thing it says, and a
+ * status carried only by colour is a status half the people reading it do not
+ * have — so a queued ring, a turning ring, a tick and a triangle are different
+ * before anything is tinted.
+ *
+ * Not exported from the package. Two components draw it and neither wants a
+ * consumer's version of it; if that changes it is one line in `index.ts`.
+ */
+export declare function StateGlyph({ state }: {
+    state: WorkState;
+}): import("react").JSX.Element;

package/dist/turnParts/turnParts.d.ts

@@ -0,0 +1,156 @@
+import { ReasoningState } from '../Reasoning/Reasoning';
+import { Thought } from '../ChainOfThought/ChainOfThought';
+import { Source } from '../Sources/Sources';
+import { Task } from '../TaskList/TaskList';
+import { ToolState } from '../Tool/Tool';
+import { Decision } from '../Approval/Approval';
+import { Answer, Question } from '../QuestionCard/types';
+import { SystemTone } from '../SystemMessage/SystemMessage';
+import { ArtifactKind, ArtifactState } from '../Artifact/ArtifactCard';
+/**
+ * The parts of a turn that are not the answer's prose.
+ *
+ * An answer used to be one string, and everything the agent tier draws had
+ * nowhere to live: a tool call, a plan and a block of reasoning all flattened
+ * into the same text or did not arrive at all. These are what a turn carries
+ * alongside `ai`.
+ *
+ * Every part has an `id` and parts are **merged by it**, which is what makes
+ * streaming one of them bearable: send `{ kind: "reasoning", id: "r1", text }`
+ * as it grows, then `{ kind: "reasoning", id: "r1", state: "done" }` when it
+ * stops, and the text is still there. Only the fields you send change.
+ */
+export type TurnPart = {
+    kind: "reasoning";
+    id: string;
+    text?: string;
+    state?: ReasoningState;
+    /** In ms. Left out, the block times itself. */
+    duration?: number;
+} | {
+    kind: "tool";
+    id: string;
+    name: string;
+    state?: ToolState;
+    summary?: string;
+    input?: unknown;
+    output?: unknown;
+    error?: string;
+    duration?: number;
+} | {
+    kind: "tasks";
+    id: string;
+    title?: string;
+    tasks: Task[];
+    collapsible?: boolean;
+} | {
+    /**
+     * Reasoning that has structure — steps that follow from one another,
+     * rather than one block of prose. `reasoning` is the block; this is the
+     * chain. Sending both for the same stretch of thinking says it twice.
+     */
+    kind: "chain";
+    id: string;
+    steps: Thought[];
+    state?: "thinking" | "done";
+    /** In ms. Left out, the block times itself. */
+    duration?: number;
+} | {
+    /**
+     * What the answer stands on.
+     *
+     * Also what an inline `[^1]` in the prose resolves against: the citation
+     * takes the source at that position, so the list is ordered by the order
+     * the answer cites them, not by rank. Send it **before** the prose that
+     * cites it and the markers come up already knowing what they point at.
+     */
+    kind: "sources";
+    id: string;
+    sources: Source[];
+    title?: string;
+    collapsible?: boolean;
+} | {
+    /**
+     * Something the agent wants to do, and has not done yet.
+     *
+     * Data rather than JSX, like every other part: a part is what a stream
+     * can send, and a stream cannot send a component. The tool it names is
+     * drawn for it, unrun.
+     */
+    kind: "approval";
+    id: string;
+    title: string;
+    description?: string;
+    tool?: {
+        name: string;
+        input?: unknown;
+    };
+    /** `null` or absent while it is still being asked. */
+    decision?: Decision | null;
+} | {
+    kind: "question";
+    id: string;
+    /** What this step is about, at the top of the group. */
+    title?: string;
+    questions: Question[];
+    /** Owned by the host: the row reports an answer, it does not keep one. */
+    answers?: Record<string, Answer | undefined>;
+    activeIndex?: number | null;
+    collapsible?: boolean;
+    readOnly?: boolean;
+} | {
+    /**
+     * Something that happened to the conversation rather than in it — the
+     * window filling, the model changing partway through, a connection
+     * going. A part rather than a component the host drops between rows,
+     * because those are the two ways anything reaches a conversation here
+     * and only one of them can be sent down a stream.
+     */
+    kind: "notice";
+    id: string;
+    text: string;
+    tone?: SystemTone;
+} | {
+    /**
+     * Something the answer produced that is bigger than the answer — a plan,
+     * a document, a file. The card in the transcript is a window onto it;
+     * pressing that card is what opens the pane.
+     *
+     * `content` is absent while it is being written, which is the usual way
+     * one arrives: the title comes first and the card shimmers it.
+     */
+    kind: "artifact";
+    id: string;
+    title: string;
+    /** What it is, in a word or two — "8 weeks", "Python". */
+    meta?: string;
+    /** How the preview is drawn. Defaults to code. */
+    preview?: ArtifactKind;
+    lang?: string;
+    content?: string;
+    state?: ArtifactState;
+};
+/**
+ * An update to a part, which is a part with everything optional but the two
+ * fields that say which one it is.
+ *
+ * This is what a stream and a host actually send. Once a tool call is on
+ * screen, saying it finished should be `{ kind: "tool", id, state: "done" }`
+ * and nothing else — repeating the name to satisfy a type is how a field that
+ * was not meant to change gets overwritten with whatever was easiest to type.
+ */
+export type TurnPartUpdate = {
+    [K in TurnPart["kind"]]: {
+        kind: K;
+        id: string;
+    } & Partial<Omit<Extract<TurnPart, {
+        kind: K;
+    }>, "kind" | "id">>;
+}[TurnPart["kind"]];
+/**
+ * Fold one update into a turn's list, by id.
+ *
+ * A shallow merge, deliberately: the fields left out keep the values they had.
+ * Sending a state change should not wipe the text that arrived before it.
+ */
+export declare function mergeParts(parts: TurnPart[], incoming: TurnPartUpdate): TurnPart[];

package/dist/useChatTurns/useChatTurns.d.ts

@@ -0,0 +1,127 @@
+import { Attachment } from '../Attachments/Attachments';
+import { ChatInputState } from '../ChatInput/ChatInput';
+import { TurnPart, TurnPartUpdate } from '../turnParts/turnParts';
+/** One answer this turn has had. */
+export interface TurnVersion {
+    id: string;
+    ai: string;
+    parts: TurnPart[];
+}
+export interface ChatTurn {
+    id: string;
+    /** What the person asked. */
+    user: string;
+    /** What went with it. */
+    attachments?: Attachment[];
+    /**
+     * Every answer this turn has had, oldest first.
+     *
+     * Regenerating used to overwrite the answer, which threw away the one being
+     * compared against — the reason anybody presses regenerate is to see whether
+     * a second attempt is better, and there is no "better" once the first is
+     * gone. Each attempt is kept and `versionIndex` says which is on screen.
+     *
+     * Empty until the first answer starts, and absent on a turn a host built by
+     * hand — the same tolerance `parts` has.
+     */
+    versions?: TurnVersion[];
+    /** Which of `versions` is in `ai` and `parts`. */
+    versionIndex?: number;
+    /** What has arrived of the answer so far. */
+    ai: string;
+    /**
+     * Everything the answer is made of that is not its prose — reasoning, tool
+     * calls, a plan, a question being asked. Merged by id as they arrive. See
+     * `TurnPart`.
+     */
+    parts: TurnPart[];
+    state: ChatInputState;
+}
+export interface SendContext {
+    /** Aborted when the reader presses stop, or the component unmounts. */
+    signal: AbortSignal;
+    turnId: string;
+    /**
+     * What was sent along with the message. Empty when nothing was.
+     *
+     * On the context rather than as a second argument: the signature already has
+     * a place for "everything about this send that is not the message", and a
+     * handler that does not care never has to mention it.
+     */
+    attachments: Attachment[];
+}
+/**
+ * Produce the reply.
+ *
+ * Return a string for a complete answer, or an async iterable to stream one.
+ * Whatever an API hands back — an SSE reader, an SDK's stream, a plain fetch —
+ * fits one of those two shapes.
+ *
+ * A streamed item is either a **delta of the answer's prose** (a string, which
+ * is appended) or a **`TurnPart`** (which is merged into the turn by its id).
+ * That is what carries a model's thinking, its tool calls and its plan through
+ * to the components that draw them; a stream of strings alone has nowhere to
+ * put any of it.
+ */
+export type SendHandler = (message: string, context: SendContext) => AsyncIterable<string | TurnPartUpdate> | Promise<string> | string;
+/**
+ * What a screen reader is told, and in which language.
+ *
+ * An answer that appears silently is an answer a blind reader never learns
+ * about, so this is on by default. It is spoken once, when the answer settles
+ * — never per character. A live region updated on every frame makes a screen
+ * reader restart the whole answer on every frame, which is worse than silence.
+ */
+export interface ChatAnnouncements {
+    /** Spoken when a request starts. `null` for silence. */
+    responding?: string | null;
+    /** Spoken when the answer settles. Return `null` for silence. */
+    answer?: (text: string) => string | null;
+}
+export interface UseChatTurnsOptions {
+    onSend: SendHandler;
+    /**
+     * Reveal rate for non-streaming replies, in characters per second. Streamed
+     * replies are paced by whatever produced them and ignore this.
+     */
+    revealSpeed?: number;
+    /** Pause after a full stop, in ms. Gives read-aloud rhythm to the reveal. */
+    sentencePause?: number;
+    /** Override the spoken strings, or pass `false` to say nothing at all. */
+    announcements?: ChatAnnouncements | false;
+}
+export interface UseChatTurnsResult {
+    turns: ChatTurn[];
+    /** Report the person's editing of a turn's input. */
+    setDraft: (id: string, value: string) => void;
+    submit: (id: string, value?: string, attachments?: Attachment[]) => void;
+    /**
+     * Show another of a turn's answers. Out-of-range is ignored rather than
+     * clamped: a caller asking for version 7 of a turn that has three has a bug,
+     * and quietly showing them version 3 hides it.
+     */
+    showVersion: (id: string, index: number) => void;
+    /** Abort the answer in flight and settle the turn where it stands. */
+    stop: () => void;
+    beginEdit: (id: string) => void;
+    cancelEdit: (id: string) => void;
+    isStreaming: boolean;
+    /**
+     * Merge a part into a turn from outside the stream.
+     *
+     * The stream is not the only thing that changes a part: a question the
+     * assistant asked is answered by the person reading it, and that answer has
+     * to land somewhere. Same merge-by-id as a streamed part.
+     */
+    updatePart: (turnId: string, part: TurnPartUpdate) => void;
+}
+/**
+ * Owns the turn list, the request in flight, and the reveal.
+ *
+ * The reason this is a hook in the package rather than an example in the
+ * README: writing it correctly means never updating state faster than the
+ * display can show it, and leaving finished turns referentially untouched so
+ * they can bail out of rendering. Both are easy to get wrong, and getting them
+ * wrong is invisible until a conversation grows long.
+ */
+export declare function useChatTurns({ onSend, revealSpeed, sentencePause, announcements, }: UseChatTurnsOptions): UseChatTurnsResult;

package/dist/voice/useVoiceInput.d.ts

@@ -0,0 +1,79 @@
+import { RefObject } from 'react';
+/**
+ * The microphone, and everything around turning it into text except the part
+ * that is a service.
+ *
+ * The division is the same one the artifact pane settled: the kit owns what is
+ * the same in every product and the host owns what differs. Permission,
+ * recording, the level of the incoming signal and the states in between are
+ * identical wherever this ships — sixty lines every host would otherwise write
+ * again, slightly differently. Turning audio into words is a choice between
+ * Whisper, Deepgram, a local model and somebody's own endpoint, and a kit that
+ * chose one for its consumers would be wrong for most of them.
+ *
+ * So this records and hands over a `Blob`. What comes back is text.
+ *
+ * **What that costs, stated rather than discovered:** the browser's own
+ * `SpeechRecognition` cannot be reached through this, because it insists on
+ * holding the microphone itself and will not take a recording. It is the only
+ * free transcriber there is, and this shuts the door on it. The door stays
+ * shut on purpose: a kit that let each host drive the microphone would ship
+ * four chats that behave differently and call it flexibility.
+ */
+export type VoiceState = 
+/** No `getUserMedia` — an insecure context, or a browser without it. */
+"unsupported" | "idle"
+/** The browser's permission prompt is up. It owns that dialog, not us. */
+ | "requesting" | "listening"
+/** Recording is over and the host is working on it. */
+ | "transcribing"
+/** Refused. Not an error: the browser will not ask again on its own. */
+ | "denied" | "failed";
+export interface TranscribeContext {
+    /** Aborts when the reader cancels, or when the component goes away. */
+    signal: AbortSignal;
+    /** What the recorder actually produced, which is not the same everywhere. */
+    mimeType: string;
+}
+/**
+ * Audio in, words out.
+ *
+ * Return a string, a promise of one, or an async iterable of **deltas** — the
+ * same three shapes `onSend` takes, and deltas accumulate the same way, so a
+ * long dictation can appear as it is recognised rather than all at the end.
+ */
+export type TranscribeHandler = (audio: Blob, context: TranscribeContext) => string | Promise<string> | AsyncIterable<string>;
+export interface UseVoiceInputOptions {
+    onTranscribe?: TranscribeHandler;
+    /**
+     * Called with the transcript so far, every time it grows. Cumulative rather
+     * than per-delta: the caller is putting this inside a string it already
+     * holds, and giving it the whole run means it does not have to remember
+     * where the last one ended.
+     */
+    onTranscript?: (text: string) => void;
+    /** Called once when a recording has been fully transcribed. */
+    onDone?: (text: string) => void;
+    /**
+     * The element the level is written onto, as `--ick-voice-level`, from 0 to 1.
+     *
+     * A number this component re-rendered on would be sixty renders a second for
+     * a decoration. This is the same decision the highlighter's hover made after
+     * it cost 28 DOM mutations per crossing: the value the browser needs goes
+     * straight to the browser.
+     */
+    meterRef?: RefObject<HTMLElement | null>;
+}
+export interface VoiceInput {
+    state: VoiceState;
+    /** Whether a microphone can be asked for at all. */
+    supported: boolean;
+    /** Why it failed, when it did. Safe to show. */
+    error: string | null;
+    start: () => void;
+    stop: () => void;
+    toggle: () => void;
+    /** Forget a refusal, so the button can be offered again. */
+    reset: () => void;
+}
+export declare function useVoiceInput({ onTranscribe, onTranscript, onDone, meterRef, }: UseVoiceInputOptions): VoiceInput;

package/package.json

@@ -0,0 +1,95 @@
+{
+  "name": "inline-chat-kit",
+  "version": "0.49.0",
+  "description": "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.",
+  "keywords": [
+    "react",
+    "chat",
+    "ai",
+    "chatbot",
+    "chat-ui",
+    "llm",
+    "streaming",
+    "assistant",
+    "component-library",
+    "design-system",
+    "accessible"
+  ],
+  "license": "MIT",
+  "author": "bogstebole",
+  "homepage": "https://github.com/bogstebole/chat-experience#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bogstebole/chat-experience.git",
+    "directory": "packages/inline-chat-kit"
+  },
+  "bugs": {
+    "url": "https://github.com/bogstebole/chat-experience/issues"
+  },
+  "type": "module",
+  "sideEffects": [
+    "*.css"
+  ],
+  "files": [
+    "dist",
+    "CHANGELOG.md",
+    "theming.md"
+  ],
+  "main": "./dist/inline-chat-kit.js",
+  "module": "./dist/inline-chat-kit.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/inline-chat-kit.js"
+    },
+    "./styles.css": "./dist/inline-chat-kit.css",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -b && vite build",
+    "dev": "vite build --watch",
+    "prepare": "npm run build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc -b --noEmit false --emitDeclarationOnly false --pretty",
+    "storybook": "storybook dev -p 6006 --no-open",
+    "build-storybook": "storybook build"
+  },
+  "peerDependencies": {
+    "lucide-react": ">=0.400.0",
+    "motion": "^12.0.0",
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@storybook/react-vite": "^10.5.10",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
+    "@testing-library/user-event": "^14.6.6",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^6.0.1",
+    "jsdom": "^29.1.1",
+    "lucide-react": "^1.14.0",
+    "motion": "^12.40.0",
+    "react": "^19.2.5",
+    "react-dom": "^19.2.5",
+    "remark-gfm": "^4.0.1",
+    "remark-parse": "^11.0.0",
+    "storybook": "^10.5.10",
+    "typescript": "~6.0.2",
+    "unified": "^11.0.5",
+    "vite": "^8.0.10",
+    "vite-plugin-dts": "^4.5.4",
+    "vitest": "^3.2.7",
+    "vitest-axe": "^0.1.0"
+  },
+  "dependencies": {
+    "highlight.js": "^11.11.0",
+    "lowlight": "^3.3.0"
+  }
+}