@backmatter/studio 0.0.7 → 0.0.9

package/src/chat/LiveStatus.tsx

@@ -3,12 +3,19 @@
 // One-line live status for a chat turn: shimmering label that tracks the
 // current thought or tool, plus an elapsed timer. Stays a single row so
 // thinking / acting doesn't stack into a transcript of its own.
-import { useEffect, useRef, useState } from "react";
+import { useEffect, useRef, useState, type ReactNode } from "react";
 import * as stylex from "@stylexjs/stylex";
 import type { UIMessage } from "ai";
 import { colors, space, type } from "../styles/tokens.stylex";
-import { formatElapsed, liveActivity, type LiveActivity } from "./chat-helpers";
+import {
+  delayThinkingReturn,
+  formatElapsed,
+  liveActivity,
+  THINKING_RETURN_MS,
+  type LiveActivity,
+} from "./chat-helpers";
 import { SparkIcon } from "./icons";
+import { motion } from "./motion";
 import { Shimmer } from "./Shimmer";
 
 export function LiveStatus({
@@ -19,8 +26,48 @@ export function LiveStatus({
   status: "submitted" | "streaming" | "ready" | "error";
 }) {
   const activity = liveActivity(parts, status);
-  if (!activity) return null;
-  return <LiveStatusLine activity={activity} />;
+  const shown = useShownActivity(activity, status);
+  if (!shown) return null;
+  return <LiveStatusLine activity={shown} />;
+}
+
+/**
+ * Keeps the first Thinking immediate. After the answer has taken the row,
+ * a return of Thinking waits so the end of the turn can't flash it.
+ */
+function useShownActivity(
+  activity: LiveActivity | null,
+  status: "submitted" | "streaming" | "ready" | "error",
+): LiveActivity | null {
+  const [shown, setShown] = useState<LiveActivity | null>(activity);
+  const answerTookOver = useRef(false);
+  const latest = useRef(activity);
+  latest.current = activity;
+  const key = activity ? `${activity.kind}:${activity.label}` : "";
+
+  useEffect(() => {
+    const next = latest.current;
+    if (!next) {
+      // The answer is on screen while the turn is still live. A Thinking
+      // line that appears in that gap is the end-of-turn flicker.
+      answerTookOver.current = status === "streaming" || status === "submitted";
+      setShown(null);
+      return;
+    }
+    if (delayThinkingReturn(status, next, answerTookOver.current)) {
+      const id = window.setTimeout(() => {
+        const pending = latest.current;
+        if (!pending || pending.kind !== "thinking") return;
+        answerTookOver.current = false;
+        setShown(pending);
+      }, THINKING_RETURN_MS);
+      return () => window.clearTimeout(id);
+    }
+    answerTookOver.current = false;
+    setShown(next);
+  }, [key, status]);
+
+  return shown;
 }
 
 function activityKey(activity: LiveActivity) {
@@ -40,26 +87,49 @@ function LiveStatusLine({ activity }: { activity: LiveActivity }) {
   }, []);
 
   return (
-    <p {...stylex.props(styles.row)} aria-live="polite" aria-atomic="true">
+    <p {...stylex.props(styles.row, motion.settle)} aria-live="polite" aria-atomic="true">
       <span {...stylex.props(styles.icon)}>
         <SparkIcon size={12} />
       </span>
-      <span {...stylex.props(styles.label)}>
+      <ActivityLabel kind={activity.kind}>
         <Shimmer>{activity.label}</Shimmer>
-      </span>
+      </ActivityLabel>
       <span {...stylex.props(styles.time)}>{formatElapsed(now - started.current.at)}</span>
     </p>
   );
 }
 
+/** Fades when the kind of activity changes. The first paint rides the row entrance. */
+function ActivityLabel({
+  kind,
+  children,
+}: {
+  kind: LiveActivity["kind"];
+  children: ReactNode;
+}) {
+  const [prevKind, setPrevKind] = useState(kind);
+  const [swap, setSwap] = useState(false);
+  if (kind !== prevKind) {
+    setPrevKind(kind);
+    setSwap(true);
+  }
+  return (
+    <span key={kind} {...stylex.props(styles.label, swap && motion.fade)}>
+      {children}
+    </span>
+  );
+}
+
 const styles = stylex.create({
   row: {
     display: "flex",
     alignItems: "center",
     gap: space.sm,
-    minHeight: 20,
+    height: 20,
     margin: 0,
+    overflow: "hidden",
     fontSize: type.sm,
+    lineHeight: "20px",
     color: colors.textMuted,
   },
   icon: {

package/src/chat/Reveal.tsx

@@ -0,0 +1,34 @@
+// packages/studio/src/chat/Reveal.tsx
+//
+// Plays the chat entrance once, on mount. Passed `active` false (history,
+// a settled turn) it renders children with no wrapper motion. A later render
+// does not replay it.
+import { useState, type ReactNode } from "react";
+import * as stylex from "@stylexjs/stylex";
+import { motion } from "./motion";
+
+export function Reveal({
+  active,
+  origin,
+  children,
+}: {
+  active: boolean;
+  origin: "start" | "end";
+  children: ReactNode;
+}) {
+  const [play] = useState(active);
+  if (!play) return children;
+  const fromEnd = origin === "end";
+  const fromStart = origin === "start";
+  return (
+    <div
+      {...stylex.props(
+        motion.rise,
+        fromEnd && motion.originEnd,
+        fromStart && motion.originStart,
+      )}
+    >
+      {children}
+    </div>
+  );
+}

package/src/chat/Shimmer.tsx

@@ -1,39 +1,81 @@
 // packages/studio/src/chat/Shimmer.tsx
 //
-// Text with a soft highlight sweeping across it. Used for transient status
-// copy ("Thinking…", running tool calls) instead of a pulsing opacity.
+// The same treatment as the Linear homepage hero: the word stays put, and a
+// soft diagonal beam travels across the letters. The beam is a separate layer,
+// masked to the glyphs, so the word itself never moves or changes size.
+// It crosses during the first three quarters of the loop, then rests fully
+// past the letters. The loop starts and ends in that same off-screen spot,
+// so the restart is invisible. Linear, because a sweep is constant speed.
 import type { ReactNode } from "react";
 import * as stylex from "@stylexjs/stylex";
 import { colors } from "../styles/tokens.stylex";
 
-const sweep = stylex.keyframes({
-  "0%": { backgroundPosition: "200% 0" },
-  "100%": { backgroundPosition: "-200% 0" },
+// 180×72, matching the hero. A narrow ink bar, rotated and blurred, so the
+// pass is a soft streak rather than a hard edge. Ink, because Studio is light:
+// the streak brings muted letters up to the text color as it passes.
+const beam =
+  'url("data:image/svg+xml,%3Csvg xmlns=\'http://www.w3.org/2000/svg\' viewBox=\'0 0 180 72\' fill=\'none\'%3E%3Cdefs%3E%3Cfilter id=\'b\' x=\'-100%25\' y=\'-100%25\' width=\'300%25\' height=\'300%25\'%3E%3CfeGaussianBlur stdDeviation=\'6\'/%3E%3C/filter%3E%3C/defs%3E%3Cg transform=\'rotate(-30 90 36)\' filter=\'url(%23b)\'%3E%3Crect x=\'72\' y=\'18\' width=\'36\' height=\'36\' fill=\'%2318181b\' fill-opacity=\'.45\'/%3E%3Crect x=\'84\' y=\'16\' width=\'12\' height=\'40\' fill=\'%2318181b\'/%3E%3C/g%3E%3C/svg%3E")';
+
+const glide = stylex.keyframes({
+  "0%, 100%": { transform: "translateX(0.001%)" },
+  "75%, 99.999%": { transform: "translateX(100%)" },
 });
 
 export function Shimmer({ children }: { children: ReactNode }) {
-  return <span {...stylex.props(styles.text)}>{children}</span>;
+  return (
+    <span {...stylex.props(styles.word)}>
+      {children}
+      <span aria-hidden {...stylex.props(styles.beam)}>
+        {children}
+      </span>
+    </span>
+  );
 }
 
 const styles = stylex.create({
-  text: {
-    color: {
-      default: "transparent",
-      "@media (prefers-reduced-motion: reduce)": colors.textMuted,
-    },
-    backgroundImage: {
-      default: `linear-gradient(90deg, ${colors.textMuted} 0%, ${colors.textMuted} 35%, ${colors.text} 50%, ${colors.textMuted} 65%, ${colors.textMuted} 100%)`,
-      "@media (prefers-reduced-motion: reduce)": "none",
+  word: {
+    position: "relative",
+    display: "inline-block",
+    maxWidth: "100%",
+    overflow: "hidden",
+    textOverflow: "ellipsis",
+    whiteSpace: "nowrap",
+    verticalAlign: "bottom",
+    color: colors.textMuted,
+    isolation: "isolate",
+  },
+  beam: {
+    position: "absolute",
+    inset: 0,
+    color: "transparent",
+    WebkitTextFillColor: "transparent",
+    pointerEvents: "none",
+    userSelect: "none",
+    contain: "paint",
+    // The glyphs are the mask. The moving layer is the ::after.
+    maskImage: "linear-gradient(#000, #000)",
+    WebkitMaskImage: "linear-gradient(#000, #000)",
+    maskClip: "text",
+    WebkitMaskClip: "text",
+    "::after": {
+      content: '""',
+      position: "absolute",
+      top: 0,
+      left: "-180px",
+      width: "calc(100% + 180px)",
+      height: "100%",
+      backgroundImage: beam,
+      backgroundSize: "180px 72px",
+      backgroundRepeat: "no-repeat",
+      backgroundPosition: "left center",
+      animationName: glide,
+      animationDuration: "2.4s",
+      animationTimingFunction: "linear",
+      animationIterationCount: "infinite",
+      pointerEvents: "none",
     },
-    backgroundSize: "200% 100%",
-    backgroundClip: "text",
-    WebkitBackgroundClip: "text",
-    animationName: {
-      default: sweep,
-      "@media (prefers-reduced-motion: reduce)": "none",
+    "@media (prefers-reduced-motion: reduce)": {
+      display: "none",
     },
-    animationDuration: "1.8s",
-    animationTimingFunction: "linear",
-    animationIterationCount: "infinite",
   },
 });

package/src/chat/chat-helpers.ts

@@ -142,6 +142,41 @@ export function liveActivity(
   return { kind: "thinking", label: "Thinking" };
 }
 
+/**
+ * Whether a reply has anything to put in the transcript. Reasoning stays on
+ * the status line, and a reply that only has that must not take a row — the
+ * list gap would shove the thinking line down.
+ */
+export function assistantShowsRow(parts: UIMessage["parts"] | undefined): boolean {
+  for (const part of parts ?? []) {
+    if (part.type === "text" && part.text.trim()) return true;
+    if (part.type === "reasoning") continue;
+    if (
+      isToolUIPart(part) &&
+      (part.state === "output-available" || part.state === "output-error")
+    ) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Wait before bringing "Thinking" back after the answer has taken the row.
+ * The text part finishes a moment before the turn does, and mounting the
+ * indicator for that gap jumps the thread. A real pause still shows it.
+ */
+export const THINKING_RETURN_MS = 450;
+
+export function delayThinkingReturn(
+  status: "submitted" | "streaming" | "ready" | "error",
+  next: LiveActivity | null,
+  answerTookOver: boolean,
+): boolean {
+  if (status !== "submitted" && status !== "streaming") return false;
+  return answerTookOver && next?.kind === "thinking";
+}
+
 export function mcpToolLabel(
   name: string,
   input: unknown,

package/src/chat/motion.ts

@@ -0,0 +1,73 @@
+// packages/studio/src/chat/motion.ts
+//
+// One entrance for chat inserts: a new message, a tool row, the live status
+// line. Ease-out so it starts immediately and settles. The travel stays short
+// so it doesn't fight the stick-to-bottom scroll. Status text that replaces
+// itself (Thinking → a tool) only fades — same curve, shorter, no movement.
+import * as stylex from "@stylexjs/stylex";
+
+/** Entering elements. Matches the dev bar. */
+const EASE_OUT = "cubic-bezier(0.23, 1, 0.32, 1)";
+
+const rise = stylex.keyframes({
+  from: { opacity: 0, transform: "translateY(6px) scale(0.98)" },
+  to: { opacity: 1, transform: "translateY(0) scale(1)" },
+});
+
+const fade = stylex.keyframes({
+  from: { opacity: 0 },
+  to: { opacity: 1 },
+});
+
+// The live status line settles in place. No travel: a translate here reads as
+// the thinking row jumping. Blur clears with the fade, same as the hero chat.
+const settle = stylex.keyframes({
+  from: { opacity: 0, filter: "blur(2px)" },
+  // A zero blur compiles to `blur()` and no longer matches `blur(2px)`,
+  // so the fade would snap. A thousandth of a pixel is still sharp.
+  to: { opacity: 1, filter: "blur(0.001px)" },
+});
+
+export const motion = stylex.create({
+  rise: {
+    animationName: rise,
+    animationDuration: "200ms",
+    animationTimingFunction: EASE_OUT,
+    // `backwards` holds the first frame only. `forwards` would leave
+    // scale(1) on the element and soften the text after it settles.
+    animationFillMode: "backwards",
+    "@media (prefers-reduced-motion: reduce)": {
+      animationName: "none",
+      animationDuration: "0s",
+    },
+  },
+  fade: {
+    animationName: fade,
+    animationDuration: "120ms",
+    animationTimingFunction: EASE_OUT,
+    animationFillMode: "backwards",
+    "@media (prefers-reduced-motion: reduce)": {
+      animationName: "none",
+      animationDuration: "0s",
+    },
+  },
+  settle: {
+    animationName: settle,
+    animationDuration: "200ms",
+    animationTimingFunction: EASE_OUT,
+    // Backwards only. Leaving `blur(0)` on the element keeps the text soft.
+    animationFillMode: "backwards",
+    "@media (prefers-reduced-motion: reduce)": {
+      animationName: "none",
+      animationDuration: "0s",
+    },
+  },
+  // User bubbles grow from the composer corner.
+  originEnd: {
+    transformOrigin: "100% 100%",
+  },
+  // Assistant text and status grow from the leading edge.
+  originStart: {
+    transformOrigin: "0% 100%",
+  },
+});

package/src/chat/useStickToBottom.ts

@@ -1,24 +1,98 @@
 // packages/studio/src/chat/useStickToBottom.ts
 //
-// Keeps a scroll container pinned to its bottom while content grows (streaming,
-// new messages), easing there with a short animation instead of jumping. The
-// user can break away by scrolling up; scrolling back down re-engages.
-import { useCallback, useEffect, useRef, type UIEvent } from "react";
+// Follows the live edge while the reader is already there, easing instead of
+// jumping. A newly sent message re-engages that follow and rises with a short
+// ease-out, so the thread moves up instead of snapping. The tail (see
+// turnSpacer) makes the destination the sent message near the top. Later
+// growth still eases. Scrolling up lets go. Scrolling back down re-engages.
+import { useCallback, useEffect, useRef, type RefObject, type UIEvent } from "react";
 
-/** Fraction of the remaining distance covered per frame (ease-out). */
+/** Fraction of the remaining distance covered per frame while streaming. */
 const EASE = 0.18;
+/** A sent message travels up quickly. Ease-out quint, under 300ms. */
+const SEND_MS = 220;
 /** Distance from the bottom (px) still considered "at the bottom". */
 const STICKY_THRESHOLD = 48;
+/** How much of the previous turn stays visible above a newly sent message. */
+export const TURN_PEEK = 64;
+
+/**
+ * Extra tail under the transcript so a sent message can sit `peek` px from the
+ * top while the scroller is at its bottom. The reply grows into that tail;
+ * once the tail is used up, the bottom is the real end again.
+ */
+export function turnSpacer({
+  clientHeight,
+  anchorOffset,
+  contentEnd,
+  paddingBottom,
+  peek,
+}: {
+  clientHeight: number;
+  /** Scroll-content y of the anchor message's top. */
+  anchorOffset: number;
+  /** Scroll-content y where the tail starts (end of messages, before padding). */
+  contentEnd: number;
+  paddingBottom: number;
+  peek: number;
+}): number {
+  const desired = Math.max(0, anchorOffset - peek);
+  return Math.max(0, desired + clientHeight - contentEnd - paddingBottom);
+}
+
+/**
+ * Where a follow should land. The tail can be taller than the sent message's
+ * slot for a moment; chasing that bottom scrolls past the slot and then
+ * snaps back when the tail shrinks.
+ */
+export function scrollTarget(max: number, slot: number | null): number {
+  if (slot == null) return max;
+  return Math.min(max, Math.max(0, slot));
+}
+
+/** cubic-bezier(0.23, 1, 0.32, 1). Same curve as the message entrance. */
+function easeOutQuint(t: number): number {
+  if (t <= 0) return 0;
+  if (t >= 1) return 1;
+  let u = t;
+  for (let i = 0; i < 6; i++) {
+    const x = bezier(u, 0.23, 0.32) - t;
+    const dx = bezierSlope(u, 0.23, 0.32);
+    if (Math.abs(dx) < 1e-6) break;
+    u = Math.min(1, Math.max(0, u - x / dx));
+  }
+  return bezier(u, 1, 1);
+}
+
+function bezier(u: number, p1: number, p2: number): number {
+  const v = 1 - u;
+  return 3 * v * v * u * p1 + 3 * v * u * u * p2 + u * u * u;
+}
+
+function bezierSlope(u: number, p1: number, p2: number): number {
+  const v = 1 - u;
+  return 3 * v * v * p1 + 6 * v * u * (p2 - p1) + 3 * u * u * (1 - p2);
+}
 
 export function useStickToBottom<T extends HTMLElement>({
   active,
   resetKey,
+  pinKey,
+  slotRef,
   deps,
 }: {
   /** Whether the container is mounted/visible. Becoming active jumps instantly. */
   active: boolean;
   /** Changing this (e.g. thread id) jumps instantly instead of animating. */
   resetKey: unknown;
+  /** Changing this (a newly sent message) re-engages follow with a quick rise. */
+  pinKey?: unknown;
+  /**
+   * Scroll offset where the sent message should sit. While set, follow will
+   * not travel past it. Null follows the real bottom (a reply that has filled
+   * the viewport, or no pinned turn).
+   */
+  slotRef?: RefObject<number | null>;
   /** Re-evaluate when any of these change (messages, status…). */
   deps: readonly unknown[];
 }) {
@@ -27,6 +101,7 @@ export function useStickToBottom<T extends HTMLElement>({
   const frame = useRef<number | null>(null);
   const lastActive = useRef(false);
   const lastKey = useRef<unknown>(resetKey);
+  const lastPin = useRef(pinKey);
 
   const stop = useCallback(() => {
     if (frame.current != null) cancelAnimationFrame(frame.current);
@@ -34,25 +109,63 @@ export function useStickToBottom<T extends HTMLElement>({
   }, []);
 
   const follow = useCallback(
-    (instant: boolean) => {
+    (mode: "instant" | "send" | "ease") => {
       const el = ref.current;
       if (!el || !stick.current) return;
       const reduceMotion =
         typeof matchMedia === "function" &&
         matchMedia("(prefers-reduced-motion: reduce)").matches;
-      if (instant || reduceMotion) {
+      if (mode === "instant" || reduceMotion) {
         stop();
         el.scrollTop = el.scrollHeight;
         return;
       }
-      if (frame.current != null) return; // already chasing the bottom
+      // A send replaces whatever chase is in flight. Streaming growth leaves
+      // a running send alone; that loop already tracks the moving target.
+      if (mode === "ease" && frame.current != null) return;
+      // The turn is already in its slot. Reply text grows into the tail;
+      // chasing a new measurement here moves the whole thread.
+      if (mode === "ease" && slotRef?.current != null) return;
+      stop();
+      if (mode === "send") {
+        const from = el.scrollTop;
+        const start = performance.now();
+        // Frozen at the slot. A tail that is still too tall must not become
+        // the destination, or the thread rises past it and snaps back.
+        const dest = scrollTarget(
+          Math.max(0, el.scrollHeight - el.clientHeight),
+          slotRef?.current ?? null,
+        );
+        const step = (ts: number) => {
+          const node = ref.current;
+          if (!node || !stick.current) {
+            stop();
+            return;
+          }
+          const max = Math.max(0, node.scrollHeight - node.clientHeight);
+          const target = Math.min(dest, max);
+          const t = Math.min(1, (ts - start) / SEND_MS);
+          node.scrollTop = from + (target - from) * easeOutQuint(t);
+          if (t < 1) {
+            frame.current = requestAnimationFrame(step);
+            return;
+          }
+          node.scrollTop = target;
+          stop();
+        };
+        frame.current = requestAnimationFrame(step);
+        return;
+      }
       const step = () => {
         const node = ref.current;
         if (!node || !stick.current) {
           stop();
           return;
         }
-        const target = node.scrollHeight - node.clientHeight;
+        const target = scrollTarget(
+          Math.max(0, node.scrollHeight - node.clientHeight),
+          slotRef?.current ?? null,
+        );
         const diff = target - node.scrollTop;
         if (Math.abs(diff) < 0.5) {
           node.scrollTop = target;
@@ -65,7 +178,7 @@ export function useStickToBottom<T extends HTMLElement>({
       };
       frame.current = requestAnimationFrame(step);
     },
-    [stop],
+    [stop, slotRef],
   );
 
   useEffect(() => {
@@ -74,12 +187,14 @@ export function useStickToBottom<T extends HTMLElement>({
       stop();
       return;
     }
-    const instant = !lastActive.current || lastKey.current !== resetKey;
+    const pinChanged = lastPin.current !== pinKey;
+    const opened = !lastActive.current || lastKey.current !== resetKey;
     lastActive.current = true;
     lastKey.current = resetKey;
-    if (instant) stick.current = true;
-    follow(instant);
-  }, [active, resetKey, follow, stop, ...deps]);
+    lastPin.current = pinKey;
+    if (opened || pinChanged) stick.current = true;
+    follow(opened ? "instant" : pinChanged ? "send" : "ease");
+  }, [active, resetKey, pinKey, follow, stop, ...deps]);
 
   useEffect(() => stop, [stop]);