inline-chat-kit 0.54.2 → 0.55.0

package/CHANGELOG.md

@@ -8,6 +8,108 @@ The versions before 1.0 follow the pre-release convention: **a breaking change
 or new public API bumps the minor**, and the patch is for fixes. Anything that would break an
 existing install is called out under **Breaking**, with what to do about it.
 
+## 0.55.0 — 2026-09-13
+
+### Added
+
+- **`ChatExperience` — the whole thing, assembled.** Every other export here is
+  a piece: a header, a scroll container, a turn, a pane. Putting them together
+  was a page's job right up until two pages did it, and then it was a copy.
+
+  ```tsx
+  <ChatExperience onSend={ask} title="Chat" placeholder="Ask anything…" />
+  ```
+
+  It holds a sent turn at the top while its answer is written and lets go when
+  it settles; titles the header from the first question actually asked rather
+  than from the first keystroke; places the artifact pane *beside* the
+  conversation rather than inside it, which is the difference between a pane
+  and a modal; announces a full context window once, through the kit's own live
+  region rather than a second one; and asks whether there is a pointer before
+  drawing a cursor for it. A host gives it content and identity — `onSend`, the
+  copy, what is in the pane, where "back" goes.
+
+  The pieces are all still exported. Assemble them yourself when your app needs
+  a shape this one does not have.
+
+- **`inline-chat-kit/demo`** — the scripted showcase behind its own entry
+  point: the landing page, the banner, and the particle-physics answers. An app
+  that never imports it never carries a line of it; the library entry is 1.8 kB
+  and the demo is 22.
+
+### Fixed
+
+- **Two variables the kit expected a host to define.** The chat stylesheet said
+  `var(--bg)` and the landing page said `--color-bg-page`, `--font-geist-sans`
+  and `--font-jetbrains-mono` — none of which this package ships. They rendered
+  correctly in a host that happened to have them and silently wrong in one that
+  did not: a header see-through over a scrolling answer, and an intro in serif
+  on a white page. All of it is on `--ick-` tokens now.
+
+### Internal
+
+- **The fork that caused the last three bug reports is gone.** Two apps each
+  kept their own copy of the assembly — 865 lines and 890, ~90% identical —
+  along with 537 byte-identical lines of scripted answers and two stylesheets.
+  Every fix went into one of them.
+
+- **`noForks.test.ts`** measures it from now on: any file under `apps/` sharing
+  more than half its substantial lines with a file in the kit fails, naming
+  both files and the share. Comments are stripped so a quotation is not a fork,
+  and whitespace is normalised so a reformat is not a defence. Watched failing
+  before it was trusted — a planted copy reports `100% (327 of 327 lines)`.
+
+- The getting-started example is now the one-liner, compiled on every build and
+  quoted into the page character for character, as before.
+
+## 0.54.3 — 2026-09-13
+
+### Fixed
+
+- **The sent message flickered a pixel up and down for the whole length of
+  every answer after the first.** Measured while a second answer was written:
+  the message sat at y=100 and flipped to 101 and back thirty-one times, with
+  the room under the conversation going 418, 379, 374, 372, 362, 360, 351
+  underneath it — a new value on every frame.
+
+  It was a feedback loop. That room is part of `scrollHeight`, the scroll
+  target is clamped to `scrollHeight`, and the room was recomputed from
+  measurements on every frame: the room moved the view, the view moved the
+  measurements, and the measurements moved the room. Sized to be *exactly*
+  enough for the anchored turn to reach the anchor, the clamp sat on a knife
+  edge and a fraction of a pixel chose the side.
+
+  A floor does not drop while the thing standing on it is still standing. So
+  while a turn is anchored the room only grows, and it is recomputed the
+  moment the anchor is let go — a long answer carries some spare room until it
+  settles, and nothing carries it afterwards. Growing stays allowed, which is
+  what keeps it self-correcting: a first measurement taken before layout is
+  final is raised by the next one rather than standing for the whole answer.
+
+  After: the message decelerates into the anchor and then holds one position
+  for the rest of the answer — 473 frames at a 680px viewport, 466 at 1400px,
+  not one of them a pixel off.
+
+### Internal
+
+- **`follow-check` has a guard for it**, and it had none before: every check
+  in there measured a *transition* — where a message lands, where the view
+  comes to rest, whether it travelled — and this fault lived in the quiet
+  stretch between them, which is why it was reported three times and "fixed"
+  twice on measurements that were each true.
+
+  The window comes from `aria-busy`, which the turn already carries for
+  screen readers while its answer arrives, so it is the window the assertion
+  names rather than one inferred from the turn's height — that one ran past
+  the end of the answer and counted the settle. The fault inside it is a
+  **reversal**, because jitter is not motion, it is motion that changes its
+  mind; the arrival is required to move and is asserted elsewhere. A creep
+  never reverses, so the back half of the window has to be a single number as
+  well, and that number the anchor.
+
+  Watched failing on the fault before it was trusted: 4 reversals at both
+  heights with the room recomputing per frame, none with the floor.
+
 ## 0.54.2 — 2026-09-12
 
 ### Fixed

package/dist/ChatExperience/ChatExperience.d.ts

@@ -0,0 +1,115 @@
+import { ReactNode } from 'react';
+import { ChatHeaderAction } from '../ChatHeader/ChatHeader';
+import { ReplyThreadPopupProps } from '../ReplyThreadPopup/ReplyThreadPopup';
+import { UseChatTurnsOptions } from '../useChatTurns/useChatTurns';
+import { FoldMotion } from '../QuestionGroup/QuestionGroup';
+import { InlineAnimConfig } from '../ChatInput/ChatInput';
+import { TranscribeHandler } from '../voice/useVoiceInput';
+import { TurnPartUpdate } from '../turnParts/turnParts';
+import { Answer } from '../QuestionCard/types';
+import { Decision } from '../Approval/Approval';
+/**
+ * The whole thing, assembled.
+ *
+ * ## Why this is in the kit and not in your page
+ *
+ * Every other export here is a piece: a header, a scroll container, a turn, a
+ * pane. Putting them together is a page's job right up until two pages do it,
+ * and then it is a copy — which is exactly what happened. The playground's
+ * page and the website's page were 865 and 890 lines of ~90% identical code,
+ * along with 537 identical lines of scripted answers and 300 of stylesheet.
+ *
+ * That copy is where the last three reported faults lived. Not in the kit: in
+ * the fact that a fix went into one page and the other kept the old one. The
+ * header rendered see-through because the second copy never defined `--bg`.
+ * The empty state snapped out of existence because the second copy never got
+ * the `AnimatePresence`. The sent message stayed pinned to the top for the
+ * rest of the session because the second copy never got the released anchor.
+ *
+ * So the assembly lives here, where a fix is made once and arrives everywhere
+ * by `npm install`. What stays a host's: the answers, the copy, the artifact's
+ * contents, the logo, where "back" goes. Content and identity — the two things
+ * a library cannot know and should not guess.
+ *
+ * ## What it does that a page would have to remember to
+ *
+ * Holds the sent turn at the top while its answer is written and lets go when
+ * it settles. Keeps a title from the first question actually asked rather than
+ * from the first keystroke. Announces a full context window once, through the
+ * kit's own live region rather than a second one. Places the artifact pane
+ * *beside* the conversation rather than inside it, which is the difference
+ * between a pane and a modal. Asks whether there is a pointer before drawing a
+ * cursor for it.
+ */
+/** The opening block, before anybody has asked anything. */
+export interface ChatExperienceEmpty {
+    title: string;
+    description?: string;
+    /** One opener per branch of your `onSend`, ideally: everything the kit can
+        draw becomes reachable by pressing something rather than by knowing what
+        to type. Sent, not typed into the box — an opener that only fills the
+        input asks somebody to press send on a sentence they did not write. */
+    suggestions?: string[];
+}
+/** What the pane shows while an artifact is open. The kit draws the pane; what
+    is inside it is the host's, which is why this returns children. */
+export interface ChatExperienceArtifact {
+    title: string;
+    meta?: string;
+    children: ReactNode;
+}
+/** A part the host drives, handed the writer for the turn it belongs to. */
+export type PartWriter = (turnId: string, part: TurnPartUpdate) => void;
+export interface ChatExperienceProps {
+    /** Where answers come from. Return a string, a promise of one, or an async
+        iterable of deltas — see `useChatTurns`. */
+    onSend: UseChatTurnsOptions["onSend"];
+    /** Speech to text. The kit records; the host transcribes. Omit and the
+        microphone does not appear. */
+    onTranscribe?: TranscribeHandler;
+    /** A follow-up asked on a passage. Omit and replying in a thread is off. */
+    onThreadReply?: ReplyThreadPopupProps["onSendMessage"];
+    /** Shown in the header until a question has actually been asked. */
+    title?: string;
+    /** Where the back control goes. */
+    backHref?: string;
+    backLabel?: string;
+    /** Extra header actions, added after the ones this manages. */
+    actions?: ChatHeaderAction[];
+    placeholder?: string;
+    empty?: ChatExperienceEmpty;
+    /** The context meter. Leave `contextTotal` off and there is no meter. A real
+        app reads this off its API's usage; a demo can count it off the text. */
+    contextTotal?: number;
+    /** What a system prompt and the tool definitions cost before anybody types. */
+    contextBase?: number;
+    /** The pane beside the conversation, asked for the artifact that is open. */
+    artifact?: (openId: string) => ChatExperienceArtifact | null;
+    /** The theme, if the host keeps it. Left off, this manages its own and puts
+        a toggle in the header; `data-theme` on the root element either way, and
+        unset until somebody chooses, so the kit follows the system preference —
+        which is what it is there for. */
+    theme?: "light" | "dark" | null;
+    onThemeChange?: (theme: "light" | "dark") => void;
+    /** The pointer-following cursor, and the rule that hides the real one. Only
+        ever where there is a pointer to replace. */
+    cursor?: boolean;
+    /** The freeform-marker / precise-selection pair in the header. */
+    selectionToggle?: boolean;
+    /** How far below the top edge a sent message comes to rest. Sets the
+        conversation's own top padding too — the two have to agree, so one number
+        writes both. */
+    anchorOffset?: number;
+    /** Room left under the composer once an answer settles. */
+    endOffset?: number;
+    /** Motion, opened up so a tuning panel can reach it. */
+    animationConfig?: InlineAnimConfig;
+    foldMotion?: FoldMotion;
+    /** How long the feed waits before its first row arrives. */
+    feedDelay?: number;
+    onAnswerQuestion?: (write: PartWriter, turnId: string, partId: string, questionId: string, answer: Answer) => void;
+    onEditQuestion?: (write: PartWriter, turnId: string, partId: string, index: number) => void;
+    onDecideApproval?: (write: PartWriter, turnId: string, partId: string, decision: Decision) => void;
+    className?: string;
+}
+export declare function ChatExperience({ onSend, onTranscribe, onThreadReply, title, backHref, backLabel, actions, placeholder, empty, contextTotal, contextBase, artifact, theme: themeProp, onThemeChange, cursor, selectionToggle, anchorOffset, endOffset, animationConfig, foldMotion, feedDelay, onAnswerQuestion, onEditQuestion, onDecideApproval, className, }: ChatExperienceProps): import("react").JSX.Element;