@haikit/client 0.6.0 → 0.6.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haikit/client",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "description": "The haikit browser runtime: streams tool payloads into interactive UI surfaces. Plain ESM, no build step, no dependencies.",
   "keywords": [
     "haikit",

package/src/transcript.d.ts

@@ -12,8 +12,10 @@ export function h<K extends keyof HTMLElementTagNameMap>(
 ): HTMLElementTagNameMap[K];
 
 /**
- * The default transcript renderer. Replaces `root`'s children on every call and
- * preserves scroll-to-bottom. Deliberately plain — this is the part you are
- * expected to replace.
+ * The default transcript renderer. Replaces `root`'s children on every call.
+ * While the reader is at the bottom, it keeps the newest content in view,
+ * surfaces included once they have mounted and as they grow. Once the reader
+ * scrolls up, it keeps their place until they scroll back down. Deliberately
+ * plain — this is the part you are expected to replace.
  */
 export function renderTranscript(root: HTMLElement, chat: Chat): void;

package/src/transcript.js

@@ -15,12 +15,109 @@ export const h = (tag, className, text) => {
 
 export function renderTranscript(root, chat) {
   const { state } = chat;
-  const atBottom = root.scrollHeight - root.scrollTop - root.clientHeight < 160;
+  const follow = follower(root);
+
+  // reset() gives a new conversation a new blocks array, and a new
+  // conversation starts at the bottom, wherever the reader was in the last.
+  if (state.blocks !== follow.blocks) Object.assign(follow, { blocks: state.blocks, stick: true, top: 0 });
+  // A scroll the reader made since the last render, whose event hasn't arrived
+  // yet: taken now, or the pin below would overwrite it. Not while an earlier
+  // render in this task is still mounting: the reader can't scroll within a
+  // task, and the position read then is one clamped to a shorter transcript.
+  else if (!follow.mounting) follow.noticeScroll();
 
   root.replaceChildren();
   for (const block of state.blocks) root.append(renderBlock(block, chat));
 
-  if (atBottom) root.scrollTop = root.scrollHeight;
+  // Surfaces mount in microtasks queued by renderBlock, in block order. This
+  // one is queued after them, so it runs once they have content and height:
+  // scrolling any earlier aims at a bottom that is about to move.
+  follow.mounting = true;
+  queueMicrotask(() => {
+    follow.mounting = false;
+    follow.stick ? follow.pin() : follow.hold();
+  });
+
+  // Surfaces can grow after they mount, as a table expands or an image loads.
+  // While following, the observer keeps the newest content in view as they do.
+  // Otherwise it returns the reader to their place, which a rebuild may have
+  // had to clamp while the surfaces above it were still short. The browser
+  // reports scrolls before resizes in a frame, so a scroll the reader has just
+  // made is already their place by then.
+  if (follow.observer) {
+    follow.observer.disconnect();
+    follow.observer.observe(root);
+    for (const child of root.children) follow.observer.observe(child);
+  }
+}
+
+/** Within this many pixels of the bottom, the reader is following new content. */
+const NEAR_BOTTOM = 40;
+
+const followers = new WeakMap();
+
+/**
+ * Whether a transcript follows new content, and where its reader is when it
+ * doesn't, kept per element across renders.
+ *
+ * Only the reader's own scrolling changes either. Read from the geometry on
+ * each render instead, both go wrong. Following breaks for good the first time
+ * content grows after the scroll, which a surface mounting does every time: the
+ * bottom is then too far away to count, and nothing scrolls there again. And
+ * one chunk of the stream can render several times before any surface mounts,
+ * so a later render reads a position the browser has already clamped to the
+ * shorter transcript.
+ */
+function follower(root) {
+  let follow = followers.get(root);
+  if (follow) return follow;
+
+  // where the transcript's own last scroll landed, so the scroll event that
+  // follows is not taken for the reader's
+  let landed = null;
+  const land = () => (landed = root.scrollTop);
+
+  follow = {
+    stick: true,
+    // where the reader last scrolled to
+    top: 0,
+    // the blocks array of the conversation shown
+    blocks: null,
+    // a render's surfaces are still to mount
+    mounting: false,
+    // the reader has scrolled, unless this is where the transcript's own
+    // last scroll landed
+    noticeScroll() {
+      if (landed !== null && Math.abs(root.scrollTop - landed) < 1) return;
+      // Content shrinking under a reader who scrolled up pulls them up to the
+      // new bottom. That is the layout moving them, not the reader, whose own
+      // scroll up always leaves the bottom: keep their place for when the
+      // content grows back.
+      const bottom = root.scrollHeight - root.clientHeight;
+      if (!follow.stick && root.scrollTop < follow.top && root.scrollTop >= bottom - 1) return;
+      landed = null;
+      follow.top = root.scrollTop;
+      follow.stick = root.scrollHeight - root.scrollTop - root.clientHeight < NEAR_BOTTOM;
+    },
+    pin() {
+      root.scrollTop = root.scrollHeight;
+      land();
+    },
+    // keep a reader who has scrolled up where they were, through a rebuild
+    hold() {
+      root.scrollTop = follow.top;
+      land();
+    },
+    observer:
+      typeof ResizeObserver === "undefined"
+        ? null
+        : new ResizeObserver(() => (follow.stick ? follow.pin() : follow.hold())),
+  };
+
+  root.addEventListener("scroll", () => follow.noticeScroll(), { passive: true });
+
+  followers.set(root, follow);
+  return follow;
 }
 
 function renderBlock(block, chat) {