inline-chat-kit 0.51.0 → 0.54.0

package/CHANGELOG.md

@@ -6,6 +6,309 @@ 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.54.0 — 2026-09-12
+
+Everything here came out of using the kit on a phone. It is better there than
+it was, and the README now says plainly that a phone is not what it is for —
+see *Where it is meant to run*.
+
+### Fixed
+
+- **A sent message travels to the top instead of cutting to it.** Sending adds
+  a whole turn at once, so the content grew by its height in a single frame and
+  the scroll was assigned its new position in that same frame. Traced at
+  1120×680 across two answers: three moves over 24px in the whole session and
+  every one of them a single frame — 154px, **416px**, 172px. The 416 was the
+  send.
+
+  The reasoning block folding away at the end was never the problem: it was
+  already gradual (−29, −58, −206 across frames) and moved the scroll by
+  nothing. Now the one move that is a decision is eased and the thousand that
+  are tracking stay instant, because easing the arrival of text would mean the
+  line being read slides for a third of a second. Measured after: `178 → 206 →
+  244 → 287 → 326 → 358 → 384`, largest single step 42px.
+
+- **The room under the last turn is measured rather than guessed.** A turn can
+  only be brought to the top if there is room under it to scroll into, and that
+  room was a `99vh` typed into the demo's stylesheet. At the end of the scroll:
+  673px of it on desktop, 836px on a phone, and the last turn **61px above the
+  top edge** — a completely blank screen at the bottom of every conversation.
+
+  `Conversation` takes a `tail` prop now, `"auto"` by default, and the
+  measurement is `screen - anchorOffset - (the anchored turn's top to the end
+  of the content)`. That makes the end of the scroll exactly where the anchored
+  turn sits at the anchor, so coming to rest and running out of scroll are the
+  same place and the room is spent holding the turn up rather than left over
+  underneath it. It also explains why chasing an answer costs nothing: the
+  content grows and the room shrinks by the same pixel, so the scroll height
+  does not move and neither does the turn at the top.
+
+- **A short answer leaves its question at the top too.** The room was being
+  sized correctly and then not rested at: resting still meant the end of the
+  *content*, which agrees with the end of the scroll only while the answer is
+  longer than the screen. Below that the difference was left unspent with the
+  turn stranded mid-view — 575px from the top in a 1174px window, with 475px
+  still to scroll.
+
+- **`endOfContent` counted the conversation's top padding twice.** A
+  conversation ending at 729 read as ending at 829, so the composer came to
+  rest 100px above the `endOffset` it was given. See **Breaking**.
+
+- **Only a control that folds lets go of the end.** Releasing the follow on any
+  press meant clicking into the composer released it too, so when an answer
+  settled there was nothing to bring the view back — and settling is also when
+  the reasoning block folds itself away, so the content shrank by its height
+  and everything above dropped into view. It read as the conversation jumping
+  to show an older message.
+
+- **An attachment's remove button is always there on a phone.** It sat under a
+  wash over the whole square, revealed on `:hover`, and there is nothing to
+  hover with — so it was drawn, in the accessibility tree, present to every
+  test that asks whether it is *there*, and unreachable. Under
+  `@media (hover: none)` it is a button in the top-right corner instead:
+  measured 28×28, 4px in from the corner of the 64px square, and a press at its
+  middle lands on it. The wash stays on a pointer, where it is the better
+  answer.
+
+- **A picture attachment was never actually drawn.** `background-image`
+  computed to `none` in both engines: the URL went into an unquoted `url()`,
+  and a bracket inside it closes the `url()` early, so the browser threw the
+  whole declaration away with no error anywhere. An SVG data URL says
+  `fill="url(#g)"`, and `encodeURIComponent` does not touch brackets — so the
+  stories showed a row of blank squares under the heading "pictures — they show
+  themselves" for as long as they had existed, and any host whose image URL
+  contains a bracket had the same.
+
+- **The reply thread stays on the screen.** It hung off the phrase from a fixed
+  top and grew downwards with nothing stopping it: at 390×844 with a passage
+  556px down, the panel ended at 920 after one reply — 76px past the bottom
+  edge, and every message after it pushed more out of reach. `placePanel`
+  returns a `maxHeight` now and stops following a phrase down once there would
+  be less than 260px left. A window short enough had this at any width.
+
+- **The disclosure row's fades work at any height.** They required
+  `clientHeight >= 630`, the thread's old fixed ceiling written again as a
+  number, so with the height coming from the screen they would have stopped
+  appearing exactly where they are most needed — the short panel is the one
+  whose content does not fit.
+
+- **`transition: all` on the glass button.** 400ms, on what the composer's mic,
+  plus and send are made of, and the X on an attachment. Among the properties
+  it was animating: `backdrop-filter`, a blur re-composited every frame for
+  four hundred milliseconds, and the same blur before and after. Named now —
+  colour and shadow at 200ms, the lift at 160ms.
+
+- **`:hover` no longer moves anything on a touchscreen.** The glass button's
+  lift and the artifact card's were ungated, and a touchscreen fires a hover on
+  tap and leaves it there until the next tap somewhere else — so they stood a
+  pixel or two high for as long as you did not touch anything. Both are inside
+  `@media (hover: hover) and (pointer: fine)`. The colour and shadow stay on
+  touch: those say "this is the one under your finger", which is true.
+
+### Added
+
+- **A bottom sheet on a phone, for the reply thread.** Below 760px it comes up
+  from the bottom instead of hanging off the phrase, with a grabber and a drag
+  to put it away — the same sheet the artifact pane becomes, with the same
+  tokens. Capping its height alone would have turned it into a letterbox: 289px
+  of thread in the lower third, under a phrase you can no longer see. It grows
+  from the bottom edge with the thread rather than standing at a fixed 88%,
+  because one reply is what a thread usually has and a sheet that is mostly
+  white reads as something that failed to load.
+
+- **The type scale rises on a touch device, and only where it earns it.**
+  `@media (pointer: coarse)` puts the prose and anything you type into at 16px
+  and caps everything else at 14. iOS zooms the page in to any editable whose
+  text computes under 16px and does not zoom back out; the answer is to stop
+  being under 16px rather than to fight the viewport.
+
+  | | before | after | mouse |
+  | --- | --- | --- | --- |
+  | prose | 12px | 16px | 12px |
+  | composer | 12px | 16px | 12px |
+  | header, chips | 13–14px | 14px | 13–14px |
+
+- **`--ick-field-size`** — the size text somebody types into draws at, which is
+  not the same idea as a step on the type scale even when they share a number.
+  `max(1rem, …)` under a coarse pointer: a floor, not an override, so a theme
+  at 18px keeps 18 and a theme at 13 gets 16.
+
+- **`--ick-icon`** — icons sized from the text beside them. Around fifty
+  `size={13..16}` call sites were fixed pixels, so raising the text left every
+  one behind. `1.15em` on touch, and `auto` elsewhere, which on an inline SVG
+  means its own width and height attributes — so a pointer keeps exactly the
+  sizes the call sites asked for.
+
+- **`--ick-control-xs` … `--ick-control-xl`** — `Button`'s five heights, as
+  tokens. They were pixels in its stylesheet, flattered 13px text, and are
+  tight around 14: the tool row was 16px of text in a 26px box. 28/32/38/44/52
+  on touch against 24/28/32/40/48. The look changes; the hit area does not —
+  that is `--ick-touch-target`, and it has always been 44px without anything
+  moving.
+
+- **`tail` on `<Conversation>`** — `"auto"` or a number of pixels. See
+  **Fixed**, and **Breaking** for what it supersedes.
+
+- **`npm run reach-check`** — what a thumb can reach on a device with no hover,
+  in both engines at 390×844, against Storybook rather than the demo (the demo
+  holds one attachment; the question needs two side by side, because these
+  buttons grow an invisible 44px box under `pointer: coarse` and two of those
+  6px apart would have the wrong one answering).
+
+- **`npm run follow-check:tall`** — the same follow check in a 1400px window.
+  The short window made every answer taller than the screen, which is the one
+  regime where two different numbers agree, so an assertion that there is
+  nowhere further to scroll passed while being unable to fail.
+
+- **`motionRules.test.ts`** — two rules read out of the stylesheets, because
+  neither is visible on screen: no `transition: all`, and no `:hover` that
+  moves something outside a pointer query. A screenshot is taken with no
+  pointer, so the second one can never appear in a picture.
+
+### Changed
+
+- **`zoom-check` measures font sizes rather than a proxy for them.** It used to
+  assert that `maximum-scale=1` was in place at the instant focus landed, for a
+  hook that locked the host's viewport while a field had focus. No engine
+  outside a real iPhone implements zoom-on-focus, so the check observed a stand-in
+  and twice went green over a version that still zoomed. A font size is the
+  input to the platform's own rule, is the same number in every engine, and is
+  either under 16 or not.
+
+### Breaking
+
+- **`endOffset` on `<Conversation>` now means what it says.** `endOfContent`
+  added the content wrapper's `offsetTop` to the last turn's, and both are
+  measured from the same positioned ancestor — so it counted the viewport's
+  padding twice and every value was effectively `endOffset + padding`. If you
+  set it, the composer will now rest closer to the bottom edge than it did by
+  exactly your conversation's top padding. **What to do:** raise `endOffset` by
+  that padding to keep what you had. The demo went from `24` to `120`.
+
+- **`--ick-conversation-tail` is written by the component.** `<Conversation>`
+  measures the room its anchor needs and sets the token on the content wrapper,
+  which beats a value set in a stylesheet. **What to do:** nothing, if you were
+  not setting it. If you were, pass `tail={<px>}` instead — a number takes the
+  measurement over, and the token remains the value used before the first
+  measurement.
+
+- **The type scale is different on a touch device.** Nothing renamed and
+  nothing removed, but a phone or tablet now draws the prose and the composer
+  at 16px, the rest at 14, icons at `1.15em`, and controls 4–8px taller. **What
+  to do:** nothing, unless you want the old sizes, in which case re-declare the
+  `--ick-text-*`, `--ick-answer-size`, `--ick-composer-size`, `--ick-field-size`,
+  `--ick-icon` and `--ick-control-*` tokens inside your own
+  `@media (pointer: coarse)` block.
+
+## 0.53.0 — 2026-09-03
+
+### Changed
+
+- **The artifact card moves instead of changing colour.** Pointing at it lifted
+  nothing and washed it grey — `--ick-inset`, ink at about 4% — while the card
+  sits on a ground that is ink at 5%. So the hover slid the card *towards* the
+  colour of the thing it is meant to be raised off, and it read as smudged
+  rather than raised. It now travels 2px up under the pointer with the shadow
+  thrown further, and 1px down under the press, and its surface never changes.
+
+  Measured, in both themes: rest 0, hover −2, press +1, with the shadow's total
+  throw going 28 → 47 → 9 and the background one value throughout. The press
+  did not work in the first cut — `.card:active` lost to
+  `.artifact:not([data-open]) .card:hover` four specificity points to two, so
+  the card stayed lifted under the finger. A press that does nothing looks like
+  a press arriving a frame late, which is why this was found by the
+  measurement and not by looking.
+
+- **Nothing is drawn for the open card any more.** It had a 2px ink ring. Next
+  to a whole pane holding the same document, that was a second answer to a
+  question already answered, and on its own it read as a selected row in a
+  list. What marks it now is that it stops lifting under the pointer — there is
+  nowhere for it to go — and `aria-expanded`, which says it outright to anybody
+  not using one. The card is the only `aria-expanded` in the kit without an
+  `aria-controls` beside it, because what it opens is not its to render.
+
+- **The pane opens and closes instead of appearing.** `ChatLayout` rendered the
+  pane the instant it had one: the conversation jumped narrower, the pane was
+  simply there, and closing it was the same in reverse. Both now animate, and
+  the two halves are deliberately not the same — the room opens flat and the
+  pane arrives with a spring in it, because `width` is what the conversation is
+  laid out against and any overshoot there re-wraps every line of the answer
+  twice on the way past. Leaving is quicker and in the other order.
+
+  The document inside is laid out **once**, at the width it ends up at, and the
+  slot uncovers it: measured at 369.59px held across every frame of an entrance
+  in which the room travelled 409px and the conversation followed it.
+
+### Added
+
+- **`--ick-shadow-float-lift` and `--ick-shadow-float-press`** — the same card
+  pointed at, and pressed. Stated per theme like `--ick-shadow-float`, and for
+  the same reason: a dark shadow has more work to do on a near-black page and
+  still must not cut the card out of it.
+
+- **`npm run showcase:artifact`** — records the card and the pane, and measures
+  what the recording is meant to show. The numbers are the half that is not
+  visible at speed.
+
+### Breaking
+
+- **`--ick-artifact-surface-hover`, `--ick-artifact-open-edge` and
+  `--ick-artifact-open-edge-width` are gone.** They were the grey hover fill
+  and the open card's ring, neither of which is drawn any more. If you were
+  overriding them, there is nothing to override; the hover is now
+  `--ick-shadow-float-lift` and the open state draws nothing.
+
+- **`--ick-artifact-pane-width` and `--ick-artifact-pane-width-wide` are in
+  `cqi`, not `%`.** `max(360px, 33cqi)` rather than `max(360px, 33%)`. The
+  slot's own width is what animates, so a percentage of it would be a
+  percentage of a number moving from zero — the pane would re-wrap its text on
+  every frame of its own entrance. Container units are measured off
+  `ChatLayout`, which is not moving. Same numbers in the same places: measured
+  at 370px in a 1120px layout and 475px in a 1440px one, unchanged from before.
+
+  If you place an `ArtifactPane` **without** `ChatLayout`, give its parent
+  `container-type: inline-size` — outside a container, `cqi` falls back to the
+  viewport.
+
+## 0.52.1 — 2026-09-03
+
+### Fixed
+
+- **The composer's editor was 16px wider than the box that clips it.**
+  `.editor` had `width: 100%` and 8px of padding either side with no
+  `box-sizing`, so its border box overflowed `.editorWrap` — which clips —
+  and the right edge of the text was cut. `scrollWidth` 292 against
+  `clientWidth` 276 on a 276px composer.
+
+  This kit has no global `box-sizing` reset on purpose, because a reset inside
+  a CSS module leaks into the host page; the rule is that every padded box
+  states its own. This one had not, and it had been that way unnoticed.
+
+  Found by the new visual QA pass on its first run, which reported it on 25
+  separate stories.
+
+## 0.52.0 — 2026-09-02
+
+### Added
+
+- **`--ick-tray` and `--ick-tray-thumb`** — a segmented control's recessed
+  track and the raised thumb in it. Every chat has one somewhere, and until now
+  the demo carried the colours in variables of its own, so the control had no
+  background anywhere else.
+
+  The thumb has to be **lighter than its tray in both themes**, and the two get
+  there from opposite ends: in light it goes all the way to paper, in dark pure
+  white is too loud so it is a wash of ink instead. Stated per theme rather
+  than mixed, because a mix cannot reverse.
+
+  Measured from painted pixels rather than declared values — with alpha
+  involved, `getComputedStyle` reports what was written, not what was drawn:
+
+  | | tray | thumb | |
+  | --- | --- | --- | --- |
+  | light | `rgb(236)` | `rgb(253)` | 1.16:1 |
+  | dark | `rgb(36)` | `rgb(72)` | 1.70:1 |
+
 ## 0.51.0 — 2026-09-02
 
 ### Added

package/README.md

@@ -10,6 +10,42 @@ 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.
 
+## 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
 
 ```bash

package/dist/Artifact/ArtifactCard.d.ts

@@ -32,7 +32,14 @@ export interface ArtifactCardProps extends Omit<HTMLAttributes<HTMLDivElement>,
     lines?: number;
     /** Open it. Without one the card is a record rather than a control. */
     onOpen?: (id: string) => void;
-    /** True while its pane is the one on screen. */
+    /**
+     * True while its pane is the one on screen.
+     *
+     * Nothing is drawn for it. The pane standing beside the conversation is
+     * already the answer, and a ring on the card was a second one — so what
+     * marks it is that it no longer lifts under the pointer, and
+     * `aria-expanded`, which says it outright to anybody not using a pointer.
+     */
     open?: boolean;
 }
 /**

package/dist/Artifact/ChatLayout.d.ts

@@ -19,6 +19,15 @@ export interface ChatLayoutProps extends HTMLAttributes<HTMLDivElement> {
      * changes it belongs in the pane's own header, where somebody can find it.
      */
     pane?: (state: PaneState) => ReactNode;
+    /**
+     * Close it — dragged down, or the conversation behind it pressed.
+     *
+     * Only used on a phone, where the pane is a sheet. Both of those are ways
+     * out that belong to the *layout* rather than to the pane: the pane owns its
+     * close button, the layout owns the gesture and the ground around it. Leave
+     * it out and the sheet has neither, which is a sheet a thumb cannot dismiss.
+     */
+    onDismiss?: () => void;
 }
 /**
  * Where the pane goes, decided once.
@@ -32,4 +41,4 @@ export interface ChatLayoutProps extends HTMLAttributes<HTMLDivElement> {
  * What is left open is the part that actually differs — what is *in* the pane.
  * See `ArtifactPane`.
  */
-export declare function ChatLayout({ children, pane, className, ...rest }: ChatLayoutProps): import("react").JSX.Element;
+export declare function ChatLayout({ children, pane, onDismiss, className, ...rest }: ChatLayoutProps): import("react").JSX.Element;

package/dist/Conversation/Conversation.d.ts

@@ -30,6 +30,57 @@ export interface ConversationProps extends HTMLAttributes<HTMLDivElement> {
      * neatly underneath and out of sight.
      */
     anchorOffset?: number;
+    /**
+     * How much room is left under the last turn when the view is at the end, in
+     * pixels.
+     *
+     * Zero puts the last line flush with the bottom edge, which is right for a
+     * transcript and wrong for this kit: the last turn *is* the composer — the
+     * input is the message — so flush means the thing you type into is jammed
+     * against the edge of the screen the moment an answer finishes. On a phone
+     * that is also where the browser's own chrome lives.
+     */
+    endOffset?: number;
+    /**
+     * The empty room under the last turn, which is what lets a turn be brought
+     * to the top at all.
+     *
+     * An element cannot be scrolled to the top of a container that ends just
+     * below it — so `anchorId` only works if there is somewhere to scroll into.
+     * That room used to be a guess written in the host's stylesheet, `99vh`,
+     * and a guess is wrong in both directions at once: too much of it and the
+     * reader can scroll a whole screen into nothing (measured: 697px of blank
+     * in a 680px view, with the last turn above the top edge), too little and
+     * the newest message cannot reach the top.
+     *
+     * `"auto"` measures it instead:
+     *
+     *     screen - anchorOffset - (the anchored turn's top to the end) - padding
+     *
+     * and the second term is the whole point. Measuring the **last turn's own
+     * height** instead — which this did first — leaves everything between the
+     * anchor and the end unaccounted for: the last turn is the composer, 44px
+     * of it, so an answer that already filled the screen still got 536px of
+     * room under it to scroll into. What the room is for is lifting the
+     * anchored turn to the top, and what stands between that turn and the
+     * bottom edge is the whole stack under it.
+     *
+     * Sized this way, the end of the scroll lands exactly where the anchored
+     * turn sits at the anchor. So the view comes to rest **at** the end of the
+     * scroll and there is nowhere further to go — the room is spent holding the
+     * turn up, not left over underneath. It shrinks as the answer grows, which
+     * is also why an answer does not have to be chased: the content grows and
+     * the room shrinks by the same pixel, so the scroll height does not move
+     * and neither does the turn at the top.
+     *
+     * Never below `endOffset`, so a turn taller than the screen still rests
+     * with the composer clear of the bottom edge instead of jammed against it.
+     *
+     * Zero unless this conversation anchors, because the room exists for
+     * anchoring. A number takes it over, in pixels; so does the
+     * `--ick-conversation-tail` token, which this writes.
+     */
+    tail?: "auto" | number;
     /** Switch the whole thing off and it is a plain scroll container. */
     follow?: boolean;
     /**

package/dist/ReplyThreadPopup/placePanel.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Where the reply panel goes, as arithmetic.
+ *
+ * A function rather than ten lines inside the render, and the reason is that
+ * it could not otherwise be tested. The panel's geometry reaches the DOM
+ * through Motion's `animate` prop, and Motion animations never complete under
+ * jsdom — so a test that reads `panel.style.left` reads the `initial` value
+ * for ever, which is the anchor. The first guard written for this passed
+ * against the broken version because of it.
+ */
+export interface Anchor {
+    left: number;
+    top: number;
+    width: number;
+}
+export interface Placement {
+    x: number;
+    y: number;
+    width: number;
+    /**
+     * The room it has between where it starts and the bottom of the screen.
+     *
+     * The panel hangs off a phrase and grows downwards as the thread fills, and
+     * nothing used to stop it growing past the bottom edge. Measured on a 390px
+     * phone with a passage 556px down: after one reply the panel ended at 920
+     * in an 844px screen, and every message after that pushed more of it
+     * further out of reach. This is what it may use, so the thread scrolls
+     * inside it instead of running off the end of the world.
+     */
+    maxHeight: number;
+}
+/**
+ * **Fit first, then place.** That order is the whole of it.
+ *
+ * The version before this widened to 480 whatever the screen was, then ran two
+ * clamps in a row: push the left edge in to the padding, then push the right
+ * edge in to `screenWidth - padding`. For a box that does not fit, the second
+ * always undoes the first — on a 390px phone it finished at `390 - 24 - 480`,
+ * so the panel sat at **x = −114** with its heading off the side of the world.
+ * Clamping a box into a space smaller than itself has no answer; the box has
+ * to be made smaller first.
+ */
+export declare function placePanel(anchor: Anchor, screenWidth: number, screenHeight?: number): Placement;