@artooi/ag-ui-web-component 0.28.0 → 0.30.0

package/src/ui/page_quote_offer.ts

@@ -0,0 +1,215 @@
+import { quotableSelection } from "./quote_selection.js";
+
+/**
+ * The same select-then-offer gesture the transcript has, in the **host page**.
+ *
+ * This exists because the recipe version of it is a trap, and a specific one.
+ * Chrome reports the internal selection of an `<input>` or `<textarea>` through
+ * `document.getSelection()` as an ordinary `Range` whose endpoints are the
+ * field's *wrapper* -- not the field. So the text reads back perfectly and the
+ * range is indistinguishable from a selection over the surrounding prose: a
+ * host listening for a page selection quotes the user's own half-typed form
+ * field back at them, and nothing about the selection says why. The only signal
+ * is `document.activeElement`, which is not where anyone looks.
+ *
+ * That, plus "do not fire for the widget's own transcript, which already offers
+ * this", plus "a fixed-position affordance strands itself on the first scroll",
+ * is three non-obvious guards. Three guards is a component feature, not a
+ * documentation snippet.
+ */
+
+/** Pixels between a selection and the offer to quote it. */
+const GAP = 6;
+
+/**
+ * The offer's own appearance.
+ *
+ * Deliberately plain and deliberately overridable: this element lands in the
+ * host's page, not in our shadow tree, so it has no theme to inherit and no
+ * business imposing one. Everything here is a single class a host stylesheet
+ * outranks by adding one more selector.
+ */
+const OFFER_CSS = `
+.ag-ui-quote-offer {
+  position: fixed;
+  z-index: 2147483000;
+  transform: translate(-50%, -100%);
+  margin: 0;
+  padding: 0.25em 0.7em;
+  border: 1px solid rgb(0 0 0 / 0.15);
+  border-radius: 999px;
+  background: Canvas;
+  color: CanvasText;
+  font: inherit;
+  font-size: 0.8rem;
+  line-height: 1.6;
+  white-space: nowrap;
+  cursor: pointer;
+  box-shadow: 0 2px 10px rgb(0 0 0 / 0.18);
+}
+
+.ag-ui-quote-offer[data-below="true"] {
+  transform: translate(-50%, 0);
+}
+`;
+
+/** A live page-side offer. */
+export interface PageQuoteOffer {
+  /** The button itself, for a host that wants to style or inspect it. */
+  readonly element: HTMLButtonElement;
+  /** Stop offering: every listener removed, the button and its styles gone. */
+  detach(): void;
+}
+
+/** What {@link attachQuoteOffer} needs to know. */
+export interface PageQuoteOfferOptions {
+  /** Where a selection is worth offering to quote. */
+  within: HTMLElement;
+  /** What the offer says. */
+  label: string;
+  /**
+   * A subtree to stay out of -- the chat widget itself.
+   *
+   * Its transcript runs this same gesture on the inside, so without this a
+   * selection there would be offered twice and quoted twice.
+   */
+  exclude: Node;
+  /** Take the offer. */
+  onQuote: (text: string) => void;
+}
+
+/**
+ * Offer to quote what the user selects inside `within`.
+ *
+ * Nothing is quoted until the offer is taken -- which is the whole point. An
+ * automatic version of this is easy to write and horrible to use: every drag
+ * made to read, to copy, or to fix a typo silently appends to whatever the user
+ * was in the middle of typing.
+ */
+export function attachQuoteOffer(options: PageQuoteOfferOptions): PageQuoteOffer {
+  const { within, exclude, onQuote } = options;
+
+  // A constructed sheet rather than an injected `<style>`: a host with a strict
+  // `style-src` drops the second one silently, leaving an unstyled pill in the
+  // middle of their page. Per attachment rather than at module scope, which
+  // this package forbids.
+  const sheet = new CSSStyleSheet();
+  sheet.replaceSync(OFFER_CSS);
+  document.adoptedStyleSheets = [...document.adoptedStyleSheets, sheet];
+
+  const button = document.createElement("button");
+  button.type = "button";
+  button.className = "ag-ui-quote-offer";
+  button.textContent = options.label;
+  button.hidden = true;
+  document.body.append(button);
+
+  let quoting = "";
+
+  const hide = (): void => {
+    button.hidden = true;
+    quoting = "";
+  };
+
+  const settled = (event: Event): void => {
+    // The widget's own gesture, tested on the **event path** rather than on the
+    // selection. The path crosses shadow boundaries and the selection does not:
+    // `Node.contains` is false for a node in a shadow tree, and the shadow-aware
+    // read, given no roots, hands back endpoints rescoped up into the page --
+    // so both selection-side tests would let a transcript drag through here and
+    // quote it a second time.
+    if (event.composedPath().includes(exclude)) {
+      hide();
+      return;
+    }
+    if (fieldHasFocus()) {
+      // The user is selecting inside their own form, to edit or to copy. See
+      // the module comment: nothing about the range itself says so.
+      hide();
+      return;
+    }
+    // The pointer's own coordinates, where there was one: they decide which
+    // line of a multi-line selection the offer hangs from.
+    const near = event instanceof MouseEvent ? { x: event.clientX, y: event.clientY } : undefined;
+    const selected = quotableSelection(within, [], near);
+    if (selected === null) {
+      hide();
+      return;
+    }
+    quoting = selected.text;
+    place(button, selected.rect);
+  };
+
+  const onMouseDown = (event: MouseEvent): void => {
+    if (!button.contains(event.target as Node)) {
+      hide();
+    }
+  };
+
+  within.addEventListener("mouseup", settled);
+  within.addEventListener("keyup", settled);
+  within.addEventListener("mousedown", onMouseDown);
+  // Capture, so a scrolling pane counts and not only the window: the offer is
+  // positioned in viewport coordinates, so anything that moves the words out
+  // from under it leaves it pointing at the wrong thing.
+  document.addEventListener("scroll", hide, true);
+  window.addEventListener("resize", hide);
+
+  // Without this the press collapses the selection before the click reads it.
+  button.addEventListener("mousedown", (event) => {
+    event.preventDefault();
+  });
+  button.addEventListener("click", () => {
+    const text = quoting;
+    window.getSelection()?.removeAllRanges();
+    hide();
+    onQuote(text);
+  });
+
+  return {
+    element: button,
+    detach(): void {
+      within.removeEventListener("mouseup", settled);
+      within.removeEventListener("keyup", settled);
+      within.removeEventListener("mousedown", onMouseDown);
+      document.removeEventListener("scroll", hide, true);
+      window.removeEventListener("resize", hide);
+      button.remove();
+      document.adoptedStyleSheets = document.adoptedStyleSheets.filter((each) => each !== sheet);
+    },
+  };
+}
+
+/**
+ * Whether focus is in something the user types into.
+ *
+ * `activeElement` rather than the selection, because the selection does not
+ * say. A focused shadow host reports as the host, which is why the widget's own
+ * composer is caught by the `exclude` subtree test instead -- the two guards
+ * each cover the other's blind spot.
+ */
+function fieldHasFocus(): boolean {
+  const active = document.activeElement;
+  if (active === null) {
+    return false;
+  }
+  return (
+    active.tagName === "INPUT" ||
+    active.tagName === "TEXTAREA" ||
+    (active as HTMLElement).isContentEditable === true
+  );
+}
+
+/** Float the offer beside `rect`, kept inside the viewport. */
+function place(button: HTMLButtonElement, rect: DOMRect): void {
+  // Unhidden first: a hidden element measures zero, and its own size decides
+  // both whether it fits above the selection and how far to pull it left.
+  button.hidden = false;
+  const below = rect.top < GAP + button.offsetHeight;
+  button.dataset["below"] = String(below);
+  button.style.top = `${below ? rect.bottom + GAP : rect.top - GAP}px`;
+  const half = button.offsetWidth / 2;
+  const centre = rect.left + rect.width / 2;
+  const width = document.documentElement.clientWidth;
+  button.style.left = `${Math.min(Math.max(centre, half), width - half)}px`;
+}

package/src/ui/quote_selection.ts

@@ -0,0 +1,345 @@
+/**
+ * Reading a text selection out of the shadow tree, and shaping it for the
+ * composer.
+ *
+ * Selection is the one DOM API shadow encapsulation genuinely broke, and it
+ * broke it in two different directions. WebKit rescopes a selection made inside
+ * a shadow tree to the **host** element, so `document.getSelection()` reports
+ * the whole widget and none of the words; Chromium exposes the shadow nodes
+ * directly, so the same call reports exactly the words. `getComposedRanges` is
+ * the settled answer to both -- it hands back real endpoints for each shadow
+ * root it is *given permission to see* -- but it is recent enough that the
+ * direct read has to stay behind it.
+ */
+
+/**
+ * The longest quotation put into the composer, in characters.
+ *
+ * A cap rather than no cap because the point of a quotation is to say *which*
+ * part of an answer the next question is about. Select-all-then-quote is a
+ * gesture the transcript already answers -- it is the whole conversation, which
+ * the model has -- and pasting it back costs the user tokens to say nothing.
+ */
+export const MAX_QUOTE_CHARS = 500;
+
+/** A selection worth offering to quote. */
+export interface QuotableSelection {
+  /** The selected text, trimmed. Never empty. */
+  readonly text: string;
+  /**
+   * One **line** of the selection, for placing the affordance beside it.
+   *
+   * Deliberately not the selection's bounding box. See {@link lineToHangFrom}:
+   * the union of a selection spanning several elements has a centre with no
+   * selected text anywhere near it.
+   */
+  readonly rect: DOMRect;
+}
+
+/** Where a gesture ended, in viewport coordinates. */
+export interface Point {
+  readonly x: number;
+  readonly y: number;
+}
+
+/** A `Selection` on an engine new enough to reach into a shadow tree. */
+type ComposedSelection = Selection & {
+  getComposedRanges?: (...args: readonly unknown[]) => readonly AbstractRange[];
+};
+
+/**
+ * The current selection, when it lies wholly inside `container`.
+ *
+ * `roots` are the shadow roots the read is allowed to look inside, in the shape
+ * `getComposedRanges` itself takes. Pass the one holding `container` for a
+ * selection made in a shadow tree, or nothing at all for one made in the page.
+ *
+ * `near` is where the gesture ended, when a pointer made it -- it decides which
+ * line of a multi-line selection the offer is hung from.
+ *
+ * `null` for no selection, a collapsed one, whitespace only, or one that
+ * starts or ends outside `container` -- a drag that ran off the transcript and
+ * into the page is not a quotation from the transcript.
+ */
+export function quotableSelection(
+  container: HTMLElement,
+  roots: readonly ShadowRoot[] = [],
+  near?: Point,
+): QuotableSelection | null {
+  for (const endpoints of endpointCandidates(roots)) {
+    if (!container.contains(endpoints.startContainer)) {
+      continue;
+    }
+    if (!container.contains(endpoints.endContainer)) {
+      continue;
+    }
+    // A live `Range` regardless of what the engine handed back: `getComposedRanges`
+    // returns `StaticRange`s, which carry endpoints and nothing else -- no text,
+    // no geometry. Both are what this is for.
+    const range = document.createRange();
+    range.setStart(endpoints.startContainer, endpoints.startOffset);
+    range.setEnd(endpoints.endContainer, endpoints.endOffset);
+    const text = renderedText(range).trim();
+    if (text === "") {
+      continue;
+    }
+    return { text, rect: lineToHangFrom(range, near) };
+  }
+  return null;
+}
+
+/**
+ * Wrap `text` as a markdown blockquote, ready to be followed by a question.
+ *
+ * Markdown rather than a bespoke fence because the transcript renders markdown
+ * and the server reads markdown: a quotation that survives both ends without a
+ * convention to agree on first. The trailing blank line is what leaves the
+ * caret on a fresh paragraph, which is the whole point of quoting into a
+ * composer rather than sending straight away.
+ */
+export function asQuote(text: string): string {
+  const lines = tidy(text);
+  if (lines.length === 0) {
+    return "";
+  }
+  const capped = cap(lines.join("\n"));
+  const quoted = capped
+    .split("\n")
+    // `trimEnd` so a blank line inside the selection becomes a bare ">" rather
+    // than "> " -- trailing whitespace markdown treats as a line break.
+    .map((line) => `> ${line}`.trimEnd())
+    .join("\n");
+  return `${quoted}\n\n`;
+}
+
+/**
+ * The selection's lines, with the *markup's* whitespace taken back out.
+ *
+ * A selection crossing block elements carries the source's own layout with it:
+ * every newline and every run of indentation between one element and the next
+ * is a text node like any other. Quoting a form as marked up produced twenty-
+ * four lines of which twelve were a bare ">", the rest indented by wherever
+ * they happened to sit in the HTML. That is not a quotation of anything.
+ *
+ * Two rules, and deliberately only two. Runs of blank lines collapse to one,
+ * because the gap between two blocks is one gap however it was written. And the
+ * indentation every line shares is removed, not each line's own -- a quotation
+ * from a code block keeps its shape, which trimming each line would flatten.
+ */
+function tidy(text: string): readonly string[] {
+  const lines = text.split(/\r\n?|\n/).map((line) => line.trimEnd());
+  const indents = lines.filter((line) => line !== "").map(indentOf);
+  const shared = indents.length === 0 ? 0 : Math.min(...indents);
+  const kept: string[] = [];
+  for (const line of lines) {
+    const dedented = line.slice(shared);
+    // No leading blank lines, and never two in a row.
+    if (dedented === "" && (kept.length === 0 || kept[kept.length - 1] === "")) {
+      continue;
+    }
+    kept.push(dedented);
+  }
+  while (kept[kept.length - 1] === "") {
+    kept.pop();
+  }
+  return kept;
+}
+
+/** How many spaces of indentation `line` opens with. */
+function indentOf(line: string): number {
+  return line.length - line.trimStart().length;
+}
+
+/** `text`, cut to {@link MAX_QUOTE_CHARS} if it runs past it. */
+function cap(text: string): string {
+  return text.length > MAX_QUOTE_CHARS ? `${text.slice(0, MAX_QUOTE_CHARS).trimEnd()}...` : text;
+}
+
+/**
+ * The selected text **as rendered**, which is not what `Range.toString()` says.
+ *
+ * `toString()` concatenates the text nodes in the range and asks no questions
+ * about CSS, so a drag across an ordinary form quotes back the values of every
+ * `<option>` in a closed `<select>` -- words the user has never seen, presented
+ * to the model as something they pointed at. `checkVisibility()` is the
+ * platform's own answer to "is this actually rendered", and it reports exactly
+ * those options as hidden.
+ *
+ * Older engines without it keep the previous behaviour rather than a guess:
+ * quoting a few invisible words is a smaller failure than dropping visible ones
+ * because a hand-rolled visibility test was wrong.
+ */
+function renderedText(range: Range): string {
+  let text = "";
+  for (const node of textNodesIn(range)) {
+    // The element carries the styles; the text node has none of its own.
+    const parent = node.parentElement as HTMLElement;
+    if (!isRendered(parent)) {
+      continue;
+    }
+    // The end nodes are only partly inside the range; everything between them
+    // is wholly inside it.
+    const from = node === range.startContainer ? range.startOffset : 0;
+    const to = node === range.endContainer ? range.endOffset : node.data.length;
+    text += collapse(node.data.slice(from, to), parent);
+  }
+  return text;
+}
+
+/**
+ * Squeeze the runs of spaces the renderer squeezes, and keep the ones it keeps.
+ *
+ * Indentation between block elements is markup, not content: it is in the DOM
+ * as text nodes and it is on screen as nothing at all, because a collapsing
+ * `white-space` reduces it. Carrying it into a quotation is not merely untidy --
+ * four leading spaces inside a blockquote is a markdown **code block**, so a
+ * form quoted as marked up renders as source listing.
+ *
+ * Newlines survive on purpose, where CSS would collapse those too. They are the
+ * only record left of where one block ended and the next began, and a quotation
+ * of six form rows run together on one line is worse than one that keeps them
+ * apart. Preformatted text is passed through untouched: there the indentation
+ * *is* the content.
+ */
+function collapse(text: string, parent: HTMLElement): string {
+  if (PREFORMATTED.has(whiteSpaceOf(parent))) {
+    return text;
+  }
+  return (
+    text
+      // Whitespace *around* a newline goes with it. Leaving a space behind
+      // would indent every line of the quotation by one, for nothing.
+      .replace(/[^\S\n]*\n[^\S\n]*/g, "\n")
+      .replace(/[^\S\n]+/g, " ")
+  );
+}
+
+/** The `white-space` values under which every space is content. */
+const PREFORMATTED = new Set(["pre", "pre-wrap", "break-spaces"]);
+
+/** The computed `white-space` of `element`, or `""` where it cannot be read. */
+function whiteSpaceOf(element: HTMLElement): string {
+  return window.getComputedStyle(element).whiteSpace;
+}
+
+/** Every text node the range touches, in document order. */
+function textNodesIn(range: Range): readonly Text[] {
+  const root = range.commonAncestorContainer;
+  // A selection inside a single text node has that node as its own common
+  // ancestor, and a `TreeWalker` never visits its root.
+  if (root.nodeType === Node.TEXT_NODE) {
+    return [root as Text];
+  }
+  const found: Text[] = [];
+  const walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT);
+  for (let node = walker.nextNode(); node !== null; node = walker.nextNode()) {
+    // The walker covers the whole subtree, which reaches past both ends of the
+    // range -- a sibling paragraph above the selection is in it too.
+    if (range.intersectsNode(node)) {
+      found.push(node as Text);
+    }
+  }
+  return found;
+}
+
+/** Whether `element` is actually drawn, where the engine will say. */
+function isRendered(element: HTMLElement): boolean {
+  if (typeof element.checkVisibility !== "function") {
+    return true;
+  }
+  return element.checkVisibility({
+    contentVisibilityAuto: true,
+    opacityProperty: true,
+    visibilityProperty: true,
+  });
+}
+
+/**
+ * The line of the selection to hang the offer from.
+ *
+ * **Not the bounding box.** A drag from a narrow column of a form down to a
+ * full-width line running under the chat panel beside it produced a union
+ * reaching from the column's left edge to the far end of that line -- and its
+ * centre landed most of the way across the page, behind the panel, on a line
+ * the user had not been looking at, while the pointer had let go by the column.
+ *
+ * Note what the fix is *not*: that centre was over selected text. It was over
+ * selected text nobody could see. A union is a shape the selection does not
+ * have, so no point derived from it belongs to any particular line.
+ *
+ * `near` is where the pointer let go. The line under it is where the user is
+ * looking, and it needs no engine-specific way to ask which end of the
+ * selection is its focus -- which the shadow-aware read does not carry anyway.
+ * Without a pointer -- a keyboard selection -- the first line is the one that
+ * exists whichever way the selection was made.
+ *
+ * The bounding box remains the fallback for a range that reports no line boxes
+ * at all, which is what a DOM with no layout does.
+ */
+function lineToHangFrom(range: Range, near: Point | undefined): DOMRect {
+  const lines = [...range.getClientRects()];
+  if (lines.length === 0) {
+    return range.getBoundingClientRect();
+  }
+  if (near === undefined) {
+    return lines[0] as DOMRect;
+  }
+  let closest = lines[0] as DOMRect;
+  let shortest = distanceTo(closest, near);
+  for (const line of lines.slice(1)) {
+    const distance = distanceTo(line, near);
+    if (distance < shortest) {
+      shortest = distance;
+      closest = line;
+    }
+  }
+  return closest;
+}
+
+/** How far `point` is from the nearest edge of `rect`, or 0 inside it. */
+function distanceTo(rect: DOMRect, point: Point): number {
+  const dx = Math.max(rect.left - point.x, 0, point.x - rect.right);
+  const dy = Math.max(rect.top - point.y, 0, point.y - rect.bottom);
+  return Math.hypot(dx, dy);
+}
+
+/**
+ * Endpoint pairs to consider, best first.
+ *
+ * Both reads are offered rather than one being chosen, because which is correct
+ * is a property of the engine *and* of where the user dragged: an engine that
+ * rescopes to the host returns endpoints outside the transcript, and the caller
+ * rejects those on the same test it uses for a selection that genuinely ran off
+ * the transcript. One rule, no engine sniffing.
+ */
+function endpointCandidates(roots: readonly ShadowRoot[]): readonly AbstractRange[] {
+  const selection = window.getSelection();
+  if (selection === null) {
+    return [];
+  }
+  const candidates = [...composedRanges(selection, roots)];
+  if (selection.rangeCount > 0) {
+    candidates.push(selection.getRangeAt(0));
+  }
+  return candidates;
+}
+
+/** The shadow-aware read, or nothing on an engine that does not have it. */
+function composedRanges(
+  selection: Selection,
+  roots: readonly ShadowRoot[],
+): readonly AbstractRange[] {
+  const composed = (selection as ComposedSelection).getComposedRanges;
+  if (composed === undefined) {
+    return [];
+  }
+  try {
+    return composed.call(selection, { shadowRoots: roots });
+  } catch {
+    // The method shipped first with the shadow roots as rest parameters and
+    // only later as a dictionary member, and the earlier form rejects the
+    // options object outright rather than ignoring it. Lexical resolves the
+    // same split the same way, by trying both shapes at runtime.
+    return composed.call(selection, ...roots);
+  }
+}

package/src/ui/relative_time.ts

@@ -36,3 +36,14 @@ export function relativeTime(
   }
   return strings.weeksAgo.replace("{n}", String(Math.round(days / 7)));
 }
+
+/**
+ * A host's replacement for {@link relativeTime}.
+ *
+ * Takes an epoch-milliseconds timestamp and returns the text a row shows.
+ * `Intl.RelativeTimeFormat` is the obvious implementation and is deliberately
+ * *not* the default: a component that guessed a locale would disagree with the
+ * host page's own formatting, and being wrong in a second language is worse
+ * than being neutral in one.
+ */
+export type RelativeTimeFormatter = (timestamp: number) => string;

package/src/ui/stick_to_bottom.ts

@@ -0,0 +1,126 @@
+/** A transcript that follows new content, unless the reader has other ideas. */
+export interface StickToBottom {
+  /**
+   * New content arrived. Scrolls to the bottom only while following, so
+   * reading older messages during a run is no longer undone on the next token.
+   */
+  readonly follow: () => void;
+  /** Go to the bottom and resume following, whatever the reader was doing. */
+  readonly jump: () => void;
+  /** Whether the transcript is currently following new content. */
+  readonly following: () => boolean;
+  readonly dispose: () => void;
+}
+
+export interface StickToBottomOptions {
+  /** The scrolling element -- the message list. */
+  readonly viewport: HTMLElement;
+  /**
+   * Called whenever the answer to "should a jump-to-latest affordance show?"
+   * changes. True means the reader has scrolled away *and* has since missed
+   * something; scrolling up through a settled transcript is not a reason to
+   * nag.
+   */
+  readonly onMissedContent: (missed: boolean) => void;
+}
+
+/**
+ * How close to the bottom still counts as the bottom, in CSS pixels.
+ *
+ * Not zero: `scrollHeight - scrollTop - clientHeight` lands on fractional
+ * values under a zoom level or a fractional device pixel ratio, so an exact
+ * comparison reports "scrolled away" for a transcript that is visibly pinned.
+ */
+const BOTTOM_SLACK_PX = 4;
+
+/**
+ * Follow the foot of a scrolling transcript, and stop when the reader scrolls
+ * away.
+ *
+ * Before this, eleven separate sites assigned `scrollTop = scrollHeight`
+ * unconditionally and nothing anywhere listened for a `scroll` event -- so
+ * nothing knew the reader had scrolled up, and scrolling back through a run was
+ * undone by the next token. Stick-to-bottom with a jump-to-latest affordance is
+ * a named primitive elsewhere for exactly this reason: shadcn ships it as
+ * `MessageScroller`, AI Elements as `ConversationScrollButton`.
+ *
+ * **Telling a reader's scroll from our own is the whole problem**, and the
+ * answer here is that it does not have to be told. A programmatic scroll only
+ * ever happens while already following, and it lands at the bottom, so the
+ * `scroll` event it provokes recomputes "at the bottom" as true and changes
+ * nothing. A reader's scroll is the only kind that can move the answer.
+ *
+ * A `ResizeObserver` covers the case scroll events cannot see: the *viewport*
+ * changing size. Resizing the panel, or the keyboard opening on a phone, moves
+ * the foot without anything scrolling and without any content arriving, so a
+ * pinned transcript would silently come unpinned.
+ *
+ * ⚠ It does **not** cover content that grows after insertion -- an image
+ * decoding, a chart laying out. A `ResizeObserver` on a scroll container does
+ * not fire when its `scrollHeight` changes, so catching that means observing
+ * every child, and the payoff is one late nudge in a case the reader can fix by
+ * scrolling. Insertion itself is covered: every site that adds to the
+ * transcript calls {@link StickToBottom.follow}.
+ */
+export function createStickToBottom({
+  viewport,
+  onMissedContent,
+}: StickToBottomOptions): StickToBottom {
+  let isFollowing = true;
+  let missed = false;
+
+  const atBottom = (): boolean =>
+    viewport.scrollHeight - viewport.scrollTop - viewport.clientHeight <= BOTTOM_SLACK_PX;
+
+  const setMissed = (next: boolean): void => {
+    if (next === missed) {
+      return;
+    }
+    missed = next;
+    onMissedContent(missed);
+  };
+
+  const toBottom = (): void => {
+    viewport.scrollTop = viewport.scrollHeight;
+  };
+
+  const onScroll = (): void => {
+    isFollowing = atBottom();
+    if (isFollowing) {
+      setMissed(false);
+    }
+  };
+
+  const follow = (): void => {
+    if (isFollowing) {
+      toBottom();
+      return;
+    }
+    setMissed(true);
+  };
+
+  // Passive: this listener never calls preventDefault, and saying so keeps it
+  // off the critical path of a scroll it has no intention of blocking.
+  viewport.addEventListener("scroll", onScroll, { passive: true });
+
+  const observer = new ResizeObserver(() => {
+    if (isFollowing) {
+      toBottom();
+    }
+  });
+  observer.observe(viewport);
+
+  return {
+    follow,
+    jump: (): void => {
+      isFollowing = true;
+      setMissed(false);
+      toBottom();
+    },
+    following: (): boolean => isFollowing,
+    dispose: (): void => {
+      viewport.removeEventListener("scroll", onScroll);
+      observer.disconnect();
+    },
+  };
+}