[Feature] Add Message Scroller component

Port the shadcn Message Scroller: a chat transcript scroller that follows
the live edge, anchors new turns near the top, and jumps to the latest
message. Built on top of Message (#446) and Bubble (#445).

shadcn delegates to a closed React primitive (@shadcn/react); this is a
from-scratch Stimulus controller (ruby-ui--message-scroller) — our own
code, no external lib:

- autoScroll follow-edge: pins to the bottom while the reader is there,
  releases on wheel/touch/keyboard/scrollbar away, re-engages on jump.
- scrollAnchor: settles an appended turn near the top keeping a peek of
  the previous item (previous_item_peek).
- defaultPosition: open at end / start / last-anchor.
- preserveOnPrepend: hold the visible row when history loads in above.
- Public API for streaming/ActionCable: scrollToEnd/scrollToStart/
  scrollToMessage; new rows are picked up via MutationObserver.
- rAF-based smooth scrolling (native smooth is unreliable on a contained
  viewport), honors prefers-reduced-motion.
- a11y: content role=log + aria-relevant, button sr-only label, button
  removed from tab order while inert.

Parts: MessageScrollerProvider, MessageScroller, MessageScrollerViewport,
MessageScrollerContent, MessageScrollerItem, MessageScrollerButton.

dependencies.yml: message_scroller depends on Message + Bubble. MCP
registry, docs page, route, controller, menu and site_files updated.

Author: djalmaaraujo

docs/app/components/shared/components_list.rb

@@ -36,6 +36,7 @@ def components
           {name: "Link", path: docs_link_path},
           {name: "Masked Input", path: masked_input_path},
           {name: "Message", path: docs_message_path},
+          {name: "Message Scroller", path: docs_message_scroller_path},
           {name: "Pagination", path: docs_pagination_path},
           {name: "Popover", path: docs_popover_path},
           {name: "Progress", path: docs_progress_path},

docs/app/controllers/docs_controller.rb

@@ -170,6 +170,10 @@ def message
     render Views::Docs::Message.new
   end
 
+  def message_scroller
+    render Views::Docs::MessageScroller.new
+  end
+
   def pagination
     render Views::Docs::Pagination.new
   end

docs/app/javascript/controllers/index.js

@@ -7,9 +7,6 @@ import { application } from "./application"
 import IframeThemeController from "./iframe_theme_controller"
 application.register("iframe-theme", IframeThemeController)
 
-import ToastDemoController from "./toast_demo_controller"
-application.register("toast-demo", ToastDemoController)
-
 import RubyUi__AccordionController from "./ruby_ui/accordion_controller"
 application.register("ruby-ui--accordion", RubyUi__AccordionController)
 
@@ -76,6 +73,9 @@ application.register("ruby-ui--hover-card", RubyUi__HoverCardController)
 import RubyUi__MaskedInputController from "./ruby_ui/masked_input_controller"
 application.register("ruby-ui--masked-input", RubyUi__MaskedInputController)
 
+import RubyUi__MessageScrollerController from "./ruby_ui/message_scroller_controller"
+application.register("ruby-ui--message-scroller", RubyUi__MessageScrollerController)
+
 import RubyUi__PopoverController from "./ruby_ui/popover_controller"
 application.register("ruby-ui--popover", RubyUi__PopoverController)
 
@@ -117,3 +117,6 @@ application.register("ruby-ui--tooltip", RubyUi__TooltipController)
 
 import SidebarMenuController from "./sidebar_menu_controller"
 application.register("sidebar-menu", SidebarMenuController)
+
+import ToastDemoController from "./toast_demo_controller"
+application.register("toast-demo", ToastDemoController)

docs/app/javascript/controllers/ruby_ui/message_scroller_controller.js

@@ -0,0 +1,292 @@
+import { Controller } from "@hotwired/stimulus";
+
+// Connects to data-controller="ruby-ui--message-scroller"
+//
+// A chat transcript scroller. Owns scroll state and behavior for a
+// height-constrained message list:
+//
+//   - autoScroll: follows the live edge while the reader is pinned to the
+//     bottom, and releases the moment they scroll, wheel, drag, or key away.
+//   - scrollAnchor: when a new anchored turn is appended, settles it near the
+//     top of the viewport keeping a peek of the previous turn above it.
+//   - defaultScrollPosition: where a freshly mounted transcript opens
+//     ("end", "start" or "last-anchor").
+//   - preserveScrollOnPrepend: keeps the visible row fixed when older messages
+//     are loaded in above the current view.
+//
+// Public API (callable from other controllers/outlets or future
+// streaming/ActionCable code): scrollToEnd(), scrollToStart(),
+// scrollToMessage(id). New rows appended to the content target are picked up
+// automatically via MutationObserver — no manual call needed.
+export default class extends Controller {
+  static targets = ["viewport", "content", "button"];
+
+  static values = {
+    autoScroll: { type: Boolean, default: true },
+    previousItemPeek: { type: Number, default: 64 },
+    defaultPosition: { type: String, default: "end" },
+    preserveOnPrepend: { type: Boolean, default: true },
+    endThreshold: { type: Number, default: 32 },
+  };
+
+  connect() {
+    // Reader is considered "following" the live edge until they move away.
+    this.following = true;
+    // True only while a programmatic scroll is in flight, so reader-intent
+    // handlers don't mistake our own scrolling for the reader's.
+    this.programmatic = false;
+
+    this.onScroll = this.onScroll.bind(this);
+    this.onWheel = this.onWheel.bind(this);
+    this.onTouchStart = this.onTouchStart.bind(this);
+    this.onKeydown = this.onKeydown.bind(this);
+
+    if (this.hasViewportTarget) {
+      this.viewportTarget.addEventListener("scroll", this.onScroll, { passive: true });
+      this.viewportTarget.addEventListener("wheel", this.onWheel, { passive: true });
+      this.viewportTarget.addEventListener("touchstart", this.onTouchStart, { passive: true });
+      this.viewportTarget.addEventListener("keydown", this.onKeydown);
+    }
+
+    if (this.hasContentTarget) {
+      // Announce streamed/added messages to assistive tech at a calm pace.
+      if (!this.contentTarget.hasAttribute("role")) {
+        this.contentTarget.setAttribute("role", "log");
+      }
+      if (!this.contentTarget.hasAttribute("aria-relevant")) {
+        this.contentTarget.setAttribute("aria-relevant", "additions text");
+      }
+
+      this.observer = new MutationObserver((records) => this.onMutations(records));
+      this.observer.observe(this.contentTarget, {
+        childList: true,
+        subtree: true,
+        characterData: true,
+      });
+    }
+
+    // Apply the opening position after layout settles.
+    requestAnimationFrame(() => {
+      this.applyDefaultPosition();
+      this.updateButton();
+    });
+  }
+
+  disconnect() {
+    if (this.hasViewportTarget) {
+      this.viewportTarget.removeEventListener("scroll", this.onScroll);
+      this.viewportTarget.removeEventListener("wheel", this.onWheel);
+      this.viewportTarget.removeEventListener("touchstart", this.onTouchStart);
+      this.viewportTarget.removeEventListener("keydown", this.onKeydown);
+    }
+    this.observer?.disconnect();
+    if (this.animationFrame) cancelAnimationFrame(this.animationFrame);
+  }
+
+  // --- Reader intent -------------------------------------------------------
+
+  onScroll() {
+    if (this.programmatic) return;
+    this.following = this.isAtEnd();
+    this.updateButton();
+  }
+
+  // Any upward wheel is a deliberate move away from the live edge.
+  onWheel(event) {
+    if (event.deltaY < 0) this.release();
+  }
+
+  onTouchStart() {
+    // A touch that turns into an upward drag surfaces through onScroll; this
+    // just makes the release feel immediate when the reader grabs the list.
+    if (!this.isAtEnd()) this.release();
+  }
+
+  onKeydown(event) {
+    const navKeys = ["ArrowUp", "PageUp", "Home", "ArrowDown", "PageDown", "End", " "];
+    if (navKeys.includes(event.key)) this.release();
+  }
+
+  release() {
+    if (this.programmatic) return;
+    this.following = false;
+  }
+
+  // --- Mutations (new / prepended / streamed rows) -------------------------
+
+  onMutations(records) {
+    let appended = null;
+    let prependedHeight = 0;
+
+    for (const record of records) {
+      if (record.type !== "childList") continue;
+      for (const node of record.addedNodes) {
+        if (node.nodeType !== Node.ELEMENT_NODE) continue;
+        if (record.previousSibling === null && record.nextSibling !== null) {
+          // Inserted above existing rows → history prepend.
+          prependedHeight += node.offsetHeight || 0;
+        } else {
+          // Inserted at (or after) the end → new turn.
+          appended = node;
+        }
+      }
+    }
+
+    if (prependedHeight > 0 && this.preserveOnPrependValue) {
+      // Keep the reader's current row fixed while history loads in above.
+      this.viewportTarget.scrollTop += prependedHeight;
+    }
+
+    if (appended) {
+      const anchor = appended.matches?.("[data-scroll-anchor]")
+        ? appended
+        : appended.querySelector?.("[data-scroll-anchor]");
+      if (anchor) {
+        this.scrollToAnchor(anchor);
+      } else if (this.autoScrollValue && this.following) {
+        this.scrollToEnd();
+      }
+    } else if (this.autoScrollValue && this.following) {
+      // No new row — text streamed into the last row. Stay pinned.
+      this.scrollToEnd("auto");
+    }
+
+    this.updateButton();
+  }
+
+  // --- Public scroll commands ---------------------------------------------
+
+  scrollToEnd(behavior = "smooth") {
+    if (!this.hasViewportTarget) return;
+    this.following = true;
+    this.scrollTo(this.viewportTarget.scrollHeight, behavior);
+  }
+
+  scrollToStart(behavior = "smooth") {
+    if (!this.hasViewportTarget) return;
+    this.following = false;
+    this.scrollTo(0, behavior);
+  }
+
+  // Scroll a row with a matching messageId into view. Returns false when the
+  // target is not mounted.
+  scrollToMessage(id, behavior = "smooth") {
+    if (!this.hasContentTarget) return false;
+    const item = this.contentTarget.querySelector(`[data-message-id="${CSS.escape(id)}"]`);
+    if (!item) return false;
+    this.following = false;
+    this.scrollToAnchor(item, behavior);
+    return true;
+  }
+
+  scrollToAnchor(item, behavior = "smooth") {
+    const top = Math.max(0, item.offsetTop - this.previousItemPeekValue);
+    this.scrollTo(top, behavior);
+  }
+
+  // Bound to the scroll button's click action.
+  jumpToEnd() {
+    this.scrollToEnd();
+  }
+
+  // --- Internals -----------------------------------------------------------
+
+  // Native scrollTo({ behavior: "smooth" }) is unreliable on a contained,
+  // virtualized viewport, so we animate scrollTop ourselves with rAF. This
+  // gives us full control over completion (no scrollend dependency) and lets
+  // us honor reduced-motion.
+  scrollTo(top, behavior = "smooth") {
+    if (!this.hasViewportTarget) return;
+    const max = this.viewportTarget.scrollHeight - this.viewportTarget.clientHeight;
+    const target = Math.max(0, Math.min(top, max));
+
+    this.programmatic = true;
+    this.element.setAttribute("data-autoscrolling", "");
+    this.viewportTarget.setAttribute("data-autoscrolling", "");
+    if (this.animationFrame) cancelAnimationFrame(this.animationFrame);
+
+    if (behavior === "auto" || this.prefersReducedMotion()) {
+      this.viewportTarget.scrollTop = target;
+      this.finishScroll();
+      return;
+    }
+
+    const start = this.viewportTarget.scrollTop;
+    const distance = target - start;
+    const duration = 300;
+    let startTime = null;
+
+    const step = (now) => {
+      if (startTime === null) startTime = now;
+      const t = Math.min(1, (now - startTime) / duration);
+      // easeOutCubic
+      const eased = 1 - Math.pow(1 - t, 3);
+      this.viewportTarget.scrollTop = start + distance * eased;
+      if (t < 1) {
+        this.animationFrame = requestAnimationFrame(step);
+      } else {
+        this.finishScroll();
+      }
+    };
+    this.animationFrame = requestAnimationFrame(step);
+  }
+
+  finishScroll() {
+    this.programmatic = false;
+    this.element.removeAttribute("data-autoscrolling");
+    this.viewportTarget?.removeAttribute("data-autoscrolling");
+    this.following = this.isAtEnd();
+    this.updateButton();
+  }
+
+  prefersReducedMotion() {
+    return window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+  }
+
+  applyDefaultPosition() {
+    if (!this.hasViewportTarget) return;
+    const position = this.defaultPositionValue;
+
+    if (position === "start") {
+      this.following = false;
+      this.viewportTarget.scrollTop = 0;
+      return;
+    }
+
+    if (position === "last-anchor") {
+      const anchors = this.contentTarget?.querySelectorAll("[data-scroll-anchor]");
+      const last = anchors && anchors[anchors.length - 1];
+      // Fall back to the end when there's no anchor, or the last turn already
+      // fits in the viewport.
+      if (last && last.offsetTop - this.previousItemPeekValue > 0) {
+        this.following = false;
+        this.viewportTarget.scrollTop = Math.max(0, last.offsetTop - this.previousItemPeekValue);
+        this.updateButton();
+        return;
+      }
+    }
+
+    // Default: open at the live edge.
+    this.following = true;
+    this.viewportTarget.scrollTop = this.viewportTarget.scrollHeight;
+  }
+
+  isAtEnd() {
+    if (!this.hasViewportTarget) return true;
+    const { scrollTop, clientHeight, scrollHeight } = this.viewportTarget;
+    return scrollHeight - (scrollTop + clientHeight) <= this.endThresholdValue;
+  }
+
+  hasOverflow() {
+    if (!this.hasViewportTarget) return false;
+    return this.viewportTarget.scrollHeight - this.viewportTarget.clientHeight > this.endThresholdValue;
+  }
+
+  updateButton() {
+    if (!this.hasButtonTarget) return;
+    const active = this.hasOverflow() && !this.isAtEnd();
+    this.buttonTarget.setAttribute("data-active", active ? "true" : "false");
+    // Remove the inert button from the tab order so there are no ghost stops.
+    this.buttonTarget.setAttribute("tabindex", active ? "0" : "-1");
+  }
+}

docs/app/lib/site_files.rb

@@ -109,6 +109,7 @@ class SiteFiles
     {title: "Link", path: "/docs/link", description: "Link component with button-like and underline variants."},
     {title: "Masked Input", path: "/docs/masked_input", description: "Form input with an applied mask."},
     {title: "Message", path: "/docs/message", description: "Chat message layout pairing an avatar with bubbles, headers, and footers."},
+    {title: "Message Scroller", path: "/docs/message_scroller", description: "Chat scroll container that anchors turns, follows streamed output, and jumps to the latest message."},
     {title: "Pagination", path: "/docs/pagination", description: "Page navigation with next and previous links."},
     {title: "Popover", path: "/docs/popover", description: "Triggered rich content panel."},
     {title: "Progress", path: "/docs/progress", description: "Progress bar for task completion state."},