inline-chat-kit 0.52.0 → 0.54.1

package/getting-started.md

@@ -0,0 +1,156 @@
+# Getting started
+
+Ten minutes, one file, a chat that works with no backend. Then one paragraph to
+point it at your model.
+
+If you are looking for what each component takes, that is the
+[README](./README.md); for colours and sizes, [theming.md](./theming.md). This
+page is only the shortest path to something running.
+
+## Install
+
+```bash
+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. React 18 or 19.
+
+## The whole thing
+
+```tsx
+import { useCallback, useState } from "react";
+import { ChatTurnRow, Conversation, useChatTurns } from "inline-chat-kit";
+import "inline-chat-kit/styles.css";
+
+/** How far below the top edge a sent message comes to rest. */
+const ANCHOR = 24;
+
+export function MinimalChat() {
+  /* Which turn to hold at the top. Kept here rather than inside the kit
+     because "which message am I looking at" is the host's question: you may
+     want it to follow a regenerate, a jump from a sidebar, or nothing at all. */
+  const [anchored, setAnchored] = useState<string | null>(null);
+
+  const { turns, setDraft, submit, stop, beginEdit, cancelEdit } = useChatTurns({
+    /* Return a string, a promise of one, or an async iterable of deltas. The
+       kit has no answers of its own — return nothing and nothing appears. */
+    onSend: async (message) => `You said: ${message}`,
+  });
+
+  const send = useCallback(
+    (id: string, value: string) => {
+      setAnchored(id);
+      submit(id, value);
+    },
+    [submit]
+  );
+
+  /* Held while the answer is arriving, let go when it settles — otherwise the
+     question stays pinned to the top for ever and the composer, which is the
+     last turn, sits below the fold. */
+  const holding = turns.find((turn) => turn.id === anchored);
+  const anchorId =
+    holding && holding.state !== "resting" ? `turn-${holding.id}` : undefined;
+
+  return (
+    <div style={{ display: "flex", flexDirection: "column", height: "100dvh" }}>
+      <Conversation
+        anchorId={anchorId}
+        /* Match whatever padding sits above the conversation, or a turn
+           brought to the top lands underneath it. */
+        anchorOffset={ANCHOR}
+        /* Room left under the composer when an answer settles. */
+        endOffset={ANCHOR}
+        style={{ padding: ANCHOR }}
+      >
+        {turns.map((turn, i) => (
+          <ChatTurnRow
+            key={turn.id}
+            turn={turn}
+            /* The last turn is the composer: this is what makes it one. */
+            isActiveInput={
+              i === turns.length - 1 &&
+              (turn.state === "idle" || turn.state === "typing")
+            }
+            /* Pass the hook's own functions straight through — they are stable,
+               and `ChatTurnRow` is memoised on them. An arrow made during
+               render hands the memo a new prop every time. */
+            onDraft={setDraft}
+            onSubmit={send}
+            onStop={stop}
+            onEdit={beginEdit}
+            onCancelEdit={cancelEdit}
+            placeholder="Ask anything…"
+          />
+        ))}
+      </Conversation>
+    </div>
+  );
+}
+```
+
+That is a working chat: type, press enter, the pill you typed into becomes the
+bubble holding your message, it travels to the top, and the answer is revealed
+underneath it at reading pace. The last turn is always the composer for the
+next message — that is what `isActiveInput` marks, and it is the whole idea.
+
+**This file is compiled on every build of this package and a test asserts it
+matches this page character for character.** If it does not work, that is a
+bug here, not a mistake you made.
+
+## Point it at your model
+
+One property changes. `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.
+
+```tsx
+const { turns, setDraft, submit, stop, beginEdit, cancelEdit } = useChatTurns({
+  onSend: async function* (message, { signal }) {
+    const response = await fetch("/api/chat", {
+      method: "POST",
+      body: JSON.stringify({ message }),
+      signal,
+    });
+    const stream = response.body!.pipeThrough(new TextDecoderStream());
+    for await (const chunk of stream) yield chunk;
+  },
+});
+```
+
+`signal` aborts when the reader presses stop. The kit never invents an answer:
+there is no canned fallback anywhere in the package, so if your handler returns
+nothing, nothing is what appears.
+
+## Three things that are easy to get wrong
+
+**The stylesheet is not optional.** The components are CSS Modules and the
+bundled sheet carries every class they reference. Without
+`import "inline-chat-kit/styles.css"` you get an unstyled page, and it looks
+like the package is broken rather than unstyled. This bit the demo in this very
+repository: a bare side-effect import inside the kit's entry survived the dev
+server and was dropped from the production build, and every colour read as
+transparent.
+
+**`anchorOffset` has to match whatever sits above the conversation.** It is how
+far below the top edge a sent message comes to rest. Put a fixed header over
+the feed and leave this at zero, and the message is scrolled neatly underneath
+it.
+
+**Pass the hook's own functions straight through.** `ChatTurnRow` is memoised
+and that memo is load-bearing: the hook leaves untouched turns referentially
+identical when it rewrites one of them, which only pays off if the rows act on
+it. Measured before the memo existed: streaming one answer produced 366 DOM
+mutations inside an unrelated, already-finished turn. An arrow function created
+during render hands the memo a new prop every time and undoes it.
+
+## Where to go next
+
+| | |
+| --- | --- |
+| everything a turn can contain — tools, reasoning, sources, tables, code, questions, approvals | [README](./README.md#what-a-turn-carries-turnpart) |
+| colours, sizes, dark mode, one brand | [theming.md](./theming.md) |
+| the side pane for documents the answer produces | [`<ArtifactCard>`, `<ArtifactPane>`, `<ChatLayout>`](./README.md) |
+| what it looks like before the first message | [`<EmptyState>`](./README.md) |
+| where this is meant to run, and where it is not | [README](./README.md#where-it-is-meant-to-run) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "inline-chat-kit",
-  "version": "0.52.0",
+  "version": "0.54.1",
   "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",
@@ -33,6 +33,7 @@
   "files": [
     "dist",
     "CHANGELOG.md",
+    "getting-started.md",
     "theming.md"
   ],
   "main": "./dist/inline-chat-kit.js",

package/theming.md

@@ -251,3 +251,54 @@ size the answer is set at instead of drifting away from it.
 already honours `prefers-reduced-motion` on its own: transforms and layout snap
 to their final values while opacity and colour still fade, so state stays
 legible without travelling.
+
+## On a phone: two things only the host can do
+
+**First, what a phone is for here.** The kit is built and tuned for desktop and
+tablet. It runs on a phone and does not break — see *Where it is meant to run*
+in the README for what holds up, what does not, and why the inline model is a
+weaker idea on a small screen. Everything below is true on a phone; none of it
+makes a phone the target.
+
+The kit sizes itself, expands its own hit areas on a coarse pointer, and keeps
+nothing wider than its container. Two mobile faults are outside it, because
+both live in the host document rather than in any component.
+
+**The viewport meta.** Add `viewport-fit=cover` if you want the safe-area
+insets to report anything but zero:
+
+```html
+<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
+```
+
+**The zoom on focus.** iOS zooms the page in to any editable whose text
+computes under 16px, and it does not zoom back out. Tapping the composer threw
+the conversation out of frame and left it there.
+
+**The kit handles this and you do not have to do anything.** Under
+`@media (pointer: coarse)` the type scale is raised and two tokens carry a
+floor:
+
+```css
+--ick-composer-size: max(1rem, var(--ick-text-sm));
+--ick-field-size:    max(1rem, var(--ick-text-md));
+```
+
+`max()` rather than a flat `1rem`, so a theme that puts the composer at 18px
+keeps 18 and a theme that puts it at 13 gets 16 — a floor, not an override.
+Anything somebody types into should draw at `--ick-field-size`; that is the
+token the guard in `tools/mobile/zoom-check.mjs` asserts against, in both
+engines, at phone width.
+
+There were three ways out and two of them were worse.
+
+| | |
+| --- | --- |
+| `maximum-scale=1` in the meta | Works. Takes pinch-zoom away from everybody, permanently, for a fault that lasts as long as somebody is typing. |
+| Lock the scale **while a field has focus** | What this repo shipped for a while — a hook rewriting the host's viewport meta on `pointerdown`. It cost two ordering bugs, one race, and a guard that switched itself off for good once the page was zoomed. None of it could be checked: no engine outside a real iPhone implements zoom-on-focus, so every green run proved nothing. |
+| **Stop being under 16px** | What the kit does. Checkable everywhere, and there is nothing left to go wrong. |
+
+The objection to the third was always that the composer would become the
+largest text on the page, bigger than the answer it turns into — true if only
+the composer moves. So the whole scale moves, on touch devices only. 12px
+reading text on a 390px screen was too small anyway.