auricui-skill 0.0.0-stage → 0.1.2

package/skill/assets/upstream/apps/desktop/chat/src/components/prompt-editor/mention-menu.ts

@@ -0,0 +1,206 @@
+/**
+ * The `@` menu (and the `/` menu of the agent's commands): when typing counts as an `@` or a `/`, which items show,
+ * and in what order.
+ *
+ * Pure logic; the Lexical half is in MentionMenuPlugin. Kept apart so these rules can be
+ * tested on plain strings: an email address opening the menu, or the best match ranked
+ * eighth, raises no error.
+ */
+import type React from 'react';
+import type { PromptReference, PromptReferenceKind } from './prompt-text';
+
+/**
+ * One menu item.
+ *
+ * It does not know whether it stands for a moment or a file; the provider does. Here it
+ * is only an icon, a label, what typing finds it, and the reference it yields.
+ */
+export interface MentionItem {
+  /** Unique in the menu. The id of the reference it will become is simplest. */
+  id: string;
+  /** The kind of reference it yields; the menu draws the same icon as the pill. */
+  kind: PromptReferenceKind;
+  label: string;
+  /** The small text after the label: a file size, a timecode. */
+  detail?: string;
+  /** Other words that find it besides the label: English aliases, the full path. */
+  keywords?: string[];
+  /** Not usable now; with no film yet, there is no current time. */
+  disabled?: boolean;
+  /** Why it is not usable; a gray item without a reason looks broken. */
+  disabledHint?: string;
+  /** The detail is a description (an agent's command): the label keeps its width, the detail is cut. */
+  describes?: boolean;
+  /** Its own icon, instead of its kind's (an agent's command). */
+  icon?: React.ComponentType<{ size?: number; className?: string }>;
+  /**
+   * Picks it: records what it needs and returns how it appears in the sentence, possibly
+   * several references (the current selection is every selected thing), or plain text
+   * (`{ text }`: an agent's command). Null or empty means it failed (too many references,
+   * or the thing is gone).
+   */
+  select: () => PromptReference | PromptReference[] | { text: string } | null;
+}
+
+/**
+ * A group of things `@` can pick.
+ *
+ * The menu only knows groups, not moments or files. Something new to mention is a new
+ * provider in the array.
+ */
+export interface MentionProvider {
+  /** The group's id, used as the render key; unique within one menu. */
+  id: string;
+  /** The group title, already localized; this layer has no i18n. */
+  groupLabel: string;
+  items: MentionItem[];
+}
+
+/** One menu row: the item, its group, and whether the group title goes above it. */
+export interface MentionEntry {
+  item: MentionItem;
+  providerId: string;
+  groupLabel: string;
+  firstOfGroup: boolean;
+}
+
+/** The longest query after `@`; anything longer is an ordinary @ in the text. */
+const MAX_QUERY_CHARS = 32;
+
+/* ASCII characters of an email local part: after one of them, `@` does not open the
+   menu, so typing a@b.com is not taken as a mention.
+   Deliberately looser than "`@` must follow whitespace or line start": Chinese and
+   Japanese text has no spaces, so `@` must work right after a word there. */
+const EMAIL_LOCAL_CHAR = /[A-Za-z0-9._%+-]/;
+
+export interface MentionTrigger {
+  /** The index of `@` in the text; the popup anchors there and replacement starts there. */
+  leadOffset: number;
+  /** What has been typed after `@`, used to filter. */
+  query: string;
+  /** The text replaced on pick, including `@`. */
+  replaceableString: string;
+}
+
+/**
+ * Whether the text before the caret ends in an `@` being typed.
+ *
+ * Only the last `@` counts: earlier ones are already pills or ordinary characters.
+ */
+export function matchMentionTrigger(textBeforeCursor: string): MentionTrigger | null {
+  const at = textBeforeCursor.lastIndexOf('@');
+  if (at < 0) return null;
+  const before = at > 0 ? textBeforeCursor[at - 1]! : '';
+  if (before && EMAIL_LOCAL_CHAR.test(before)) return null;
+  const query = textBeforeCursor.slice(at + 1);
+  /* Whitespace ends the mention: file names can have spaces, but what follows a space is
+     usually the next word, and a lingering menu would cover it. */
+  if (query.length > MAX_QUERY_CHARS || /\s/.test(query)) return null;
+  return { leadOffset: at, query, replaceableString: textBeforeCursor.slice(at) };
+}
+
+/**
+ * Whether the message so far is a `/` being typed at its very start: an agent's command, as in its own chat (`/` in
+ * the middle of a sentence is a path or a fraction). The query is what follows, up to the first space.
+ */
+export function matchSlashTrigger(textBeforeCursor: string): MentionTrigger | null {
+  const m = /^\s*\/([^\s/]{0,40})$/.exec(textBeforeCursor);
+  if (!m) return null;
+  const at = textBeforeCursor.indexOf('/');
+  return { leadOffset: at, query: m[1]!, replaceableString: textBeforeCursor.slice(at) };
+}
+
+/* Ranking: prefix < word start < substring < subsequence (other characters in between).
+   Within a tier, an earlier match ranks higher: "video" at position 3 of my-video.mp4
+   beats position 20 of a-really-long-name-video.mp4.
+   Both are packed into one number: tier × TIER_STEP + match position. */
+const TIER_STEP = 1000;
+const TIER_PREFIX = 0;
+const TIER_WORD = 1;
+const TIER_SUBSTRING = 2;
+const TIER_SUBSEQUENCE = 3;
+
+/** Characters that separate words in file names: `-`, `_`, `.` and path separators start a word. */
+const WORD_BOUNDARY = /[\s._\-/\\]/;
+
+/**
+ * How well the text matches the query; lower is better, null is no match.
+ *
+ * The last tier is a subsequence (`bgm` matches `background-music.mp3`): file names are
+ * long and hard to remember, so a few remembered letters should be enough.
+ */
+export function scoreMentionText(text: string, query: string): number | null {
+  if (!query) return TIER_PREFIX * TIER_STEP;
+  const haystack = text.toLowerCase();
+  const needle = query.toLowerCase();
+  if (haystack.startsWith(needle)) return TIER_PREFIX * TIER_STEP;
+  const index = haystack.indexOf(needle);
+  if (index >= 0) {
+    const tier = WORD_BOUNDARY.test(haystack[index - 1] ?? '') ? TIER_WORD : TIER_SUBSTRING;
+    return tier * TIER_STEP + Math.min(index, TIER_STEP - 1);
+  }
+  const start = subsequenceStart(haystack, needle);
+  return start == null ? null : TIER_SUBSEQUENCE * TIER_STEP + Math.min(start, TIER_STEP - 1);
+}
+
+/** Matches if every character of the query appears in order; returns where the first one is. */
+function subsequenceStart(haystack: string, needle: string): number | null {
+  let start: number | null = null;
+  let cursor = 0;
+  for (const char of needle) {
+    const found = haystack.indexOf(char, cursor);
+    if (found < 0) return null;
+    if (start == null) start = found;
+    cursor = found + 1;
+  }
+  return start;
+}
+
+/** Tries the label and every keyword and keeps the best score. */
+export function scoreMentionItem(item: MentionItem, query: string): number | null {
+  let best: number | null = null;
+  for (const text of [item.label, ...(item.keywords ?? [])]) {
+    const score = scoreMentionText(text, query);
+    if (score != null && (best == null || score < best)) best = score;
+  }
+  return best;
+}
+
+/** The most rows the menu shows; with hundreds of files, typing a little more beats scrolling. */
+export const MENTION_MENU_LIMIT = 20;
+
+/**
+ * Flattens the providers into the menu's rows.
+ *
+ * Groups stay together, each one kind of thing; sorting happens only within a group.
+ */
+export function buildMentionMenu(
+  providers: MentionProvider[],
+  query: string,
+  limit: number = MENTION_MENU_LIMIT,
+): MentionEntry[] {
+  const entries: MentionEntry[] = [];
+  for (const provider of providers) {
+    provider.items
+      .map((item, order) => ({ item, order, score: scoreMentionItem(item, query) }))
+      .filter((row): row is { item: MentionItem; order: number; score: number } => row.score != null)
+      .sort((a, b) => {
+        /* Disabled items sink to the bottom of their group: they must not push down a
+           usable item or be picked by Enter. */
+        if (!!a.item.disabled !== !!b.item.disabled) return a.item.disabled ? 1 : -1;
+        if (a.score !== b.score) return a.score - b.score;
+        // Ties keep the provider's order (files come newest first).
+        return a.order - b.order;
+      })
+      .forEach((row, index) => {
+        entries.push({
+          item: row.item,
+          providerId: provider.id,
+          groupLabel: provider.groupLabel,
+          firstOfGroup: index === 0,
+        });
+      });
+  }
+  /* Cut from the end, so every remaining group keeps its first row and title. */
+  return entries.slice(0, limit);
+}

package/skill/assets/upstream/apps/desktop/chat/src/components/prompt-editor/prompt-text.ts

@@ -0,0 +1,171 @@
+/**
+ * References on the editor side: splitting markers, unknown markers, and what they
+ * expand to on send.
+ *
+ * The marker and a reference's stored shape live in `prompt-reference` in
+ * `@openfilm/shared`: the text with markers is stored, so it is a shared contract.
+ */
+import {
+  splitPromptReferenceText,
+  type PromptReference as StoredPromptReference,
+} from '@openfilm/shared';
+
+export {
+  promptReferenceToken,
+  splitPromptReferenceText,
+  stripPromptReferenceTokens,
+  type PromptTextSegment,
+} from '@openfilm/shared';
+
+/**
+ * A reference in the editor.
+ *
+ * It does not know whether it is an element, a region or a clip; the host translates
+ * that. Here it is only an icon, a label, and who handles a click.
+ *
+ * The shape lives in @openfilm/shared; this narrows `kind` to the kinds the icon table
+ * knows, since every pill inserted here needs an icon, while stored references can have
+ * kinds this UI does not know (see `promptReferenceSchema`).
+ */
+export interface PromptReference extends StoredPromptReference {
+  kind: PromptReferenceKind;
+}
+
+/**
+ * clip* = a whole clip on the timeline (an MG, a voice line), unlike time (a moment).
+ * file = a file in the project workspace; on send it becomes a path (see below).
+ * card = a canvas card. The sentence holds a pointer; the content is read on send.
+ * skill = a way of working (a package), not something in the film.
+ * range = a span of the film (in to out on the timeline); track = a whole timeline track.
+ * subtitle = a subtitle line (or some of its words), with its time in the film.
+ *
+ * Clips are six kinds rather than one `clip` only for their icons, so an MG, a video and
+ * a voice line in one sentence look different.
+ */
+export type PromptReferenceKind =
+  | 'element' | 'region' | 'time' | 'range' | 'track' | 'subtitle' | 'showcase' | 'file' | 'card' | 'skill' | 'example'
+  | 'clipMg' | 'clipVideo' | 'clipVoice' | 'clipSfx' | 'clipMusic' | 'clipCaption';
+
+/* The id prefix of a file reference, followed by the workspace-relative path, which is
+   all the reference holds. It is in the id rather than a separate table because the
+   agent needs exactly that path (to read it, or put it in <video src>), so the text
+   carries it with no translation on send. */
+const FILE_REFERENCE_PREFIX = 'file:';
+
+export function fileReferenceId(path: string): string {
+  return `${FILE_REFERENCE_PREFIX}${path}`;
+}
+
+/** Null if not a file reference (or the path is empty). */
+export function fileReferencePath(id: string): string | null {
+  if (!id.startsWith(FILE_REFERENCE_PREFIX)) return null;
+  return id.slice(FILE_REFERENCE_PREFIX.length) || null;
+}
+
+/* The id prefix of a skill reference, followed by the package name (as imported). As
+   with files, the name is all the reference holds, so it expands without the host, even
+   for a draft restored from localStorage with no references loaded. */
+const SKILL_REFERENCE_PREFIX = 'skill:';
+
+export function skillReferenceId(packageName: string): string {
+  return `${SKILL_REFERENCE_PREFIX}${packageName}`;
+}
+
+/** Null if not a skill reference (or the package name is empty). */
+export function skillReferencePackage(id: string): string | null {
+  if (!id.startsWith(SKILL_REFERENCE_PREFIX)) return null;
+  return id.slice(SKILL_REFERENCE_PREFIX.length) || null;
+}
+
+/** The skill packages this message names, deduplicated, in order. */
+export function activatedSkillIds(
+  references: readonly { id: string }[] | undefined,
+): string[] {
+  if (!references?.length) return [];
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const ref of references) {
+    const name = skillReferencePackage(ref.id);
+    if (!name || seen.has(name)) continue;
+    seen.add(name);
+    out.push(name);
+  }
+  return out;
+}
+
+/**
+ * Replaces the markers in the text with what the model reads.
+ *
+ * `render` gets the index of the reference's first appearance (from 1), in the same order
+ * as the references sent with the request, which is how the prompt lists the referenced
+ * context. That is how the model knows which item "make this blue" means.
+ *
+ * `render` returning null means unknown (a draft restored from localStorage with no
+ * references loaded, or an undo bringing back a sent pill): it is dropped and takes no
+ * number. The numbers must match collectPromptReferences exactly; an off-by-one raises
+ * no error, it just makes the model edit the wrong thing.
+ *
+ * File references are the exception: they become the path in the id, skip `render`, and
+ * take no number. No render, because a path needs no translation, and after a draft
+ * restore render would drop it as unknown. No number, because files are not in the
+ * references sent with the request (that list holds only timestamp, region and element),
+ * so numbering them would shift every later reference.
+ *
+ * `verbatim` opens the same exception to others: any reference that explains itself and
+ * is not in that list expands as is, without a number. Canvas cards use it.
+ */
+export function resolvePromptReferences(
+  text: string,
+  render: (id: string, index: number) => string | null,
+  verbatim?: (id: string) => string | null,
+): string {
+  const order = new Map<string, number>();
+  let out = '';
+  for (const segment of splitPromptReferenceText(text)) {
+    if (segment.kind === 'text') {
+      out += segment.value;
+      continue;
+    }
+    const { id } = segment;
+    const path = fileReferencePath(id);
+    if (path) {
+      out += path;
+      continue;
+    }
+    const raw = verbatim?.(id);
+    if (raw != null) {
+      out += raw;
+      continue;
+    }
+    const seen = order.get(id);
+    if (seen != null) {
+      out += render(id, seen) ?? '';
+      continue;
+    }
+    const next = order.size + 1;
+    const rendered = render(id, next);
+    if (rendered == null) continue;
+    order.set(id, next);
+    out += rendered;
+  }
+  return out;
+}
+
+/** The references used in the text, deduplicated, in order; the order is the numbering. */
+export function collectPromptReferences(
+  text: string,
+  lookup: (id: string) => PromptReference | undefined,
+): PromptReference[] {
+  const seen = new Set<string>();
+  const out: PromptReference[] = [];
+  for (const segment of splitPromptReferenceText(text)) {
+    if (segment.kind === 'text') continue;
+    const { id } = segment;
+    if (seen.has(id)) continue;
+    seen.add(id);
+    const reference = lookup(id);
+    /* Unknown markers are dropped rather than kept as empty references. */
+    if (reference) out.push(reference);
+  }
+  return out;
+}

package/skill/assets/upstream/apps/desktop/chat/src/components/useStickToBottom.ts

@@ -0,0 +1,320 @@
+'use client';
+
+import * as React from 'react';
+
+/**
+ * Keeps the conversation pinned to its latest line unless the user scrolls up.
+ *
+ * Re-renders are the wrong trigger: a streaming answer, an image finishing decoding, a
+ * code block reflowing, a finished turn collapsing into a summary, or the composer
+ * growing all change height without a new turn. So this watches size instead: a
+ * ResizeObserver on the viewport and the content re-pins whenever either changes height
+ * (the same approach as the use-stick-to-bottom library).
+ *
+ * Scrolling up releases the pin; scrolling back to the bottom resumes it. The release is
+ * decided on `wheel`, not `scroll`: while content grows every frame and the observer
+ * re-pins every frame, waiting for `scroll` makes the wheel feel stuck.
+ */
+
+/** How long the glide to the bottom takes after sending: visible, but no wait. */
+const GLIDE_MS = 360;
+
+/** How close to the bottom still counts as "at the bottom": about one line. */
+const NEAR_BOTTOM_PX = 96;
+
+export type StickToBottom = {
+  /**
+   * Goes on the overflow-y-auto box.
+   *
+   * A callback ref, not a ref object: the viewport may mount after the hook (the project
+   * shows a loading screen first). A ref object would not notify anyone, so the
+   * subscription would try once on the first frame, miss, and never follow.
+   */
+  viewportRef: (node: HTMLDivElement | null) => void;
+  /** The viewport box itself, for other hooks (the tail spacer) to measure. */
+  viewport: HTMLDivElement | null;
+  /** Goes on the box that wraps all messages (a callback ref, so a swapped content box is picked up). */
+  contentRef: (node: HTMLDivElement | null) => void;
+  /** Whether the view is at the bottom now; decides whether "Back to latest" shows. */
+  atBottom: boolean;
+  /**
+   * Pins to the bottom again and resumes following. Called on send and on "Back to latest".
+   *
+   * `smooth` glides instead of jumping, since a jump looks like a page reload. The glide
+   * re-measures the bottom every frame, because the new bubble and the spacer grow meanwhile.
+   */
+  scrollToBottom: (opts?: { smooth?: boolean }) => void;
+  /**
+   * If following, pins again at the current height now. Does not change following.
+   *
+   * For content that grows or shrinks at the bottom while the viewport stays the same,
+   * such as the padding under the asset drawer. Waiting for the observer would be one
+   * frame late, which shows as a flash when the drawer closes.
+   */
+  pinIfFollowing: () => void;
+  /**
+   * Skips pinning on the next height change and stops following, unless the view is
+   * still at the bottom once the change settles.
+   *
+   * Expanding or collapsing a summary changes height, and the observer would pin back to
+   * the bottom, pulling away the row the user just clicked.
+   */
+  skipNextPin: () => void;
+};
+
+export const StickToBottomContext = React.createContext<StickToBottom | null>(null);
+
+/**
+ * While a turn runs, it may grow but not shrink.
+ *
+ * Finished tool rows collapse into a summary while the answer keeps growing; that
+ * shrink would make the bottom-pinned view bounce back. So the running turn gets a
+ * min-height equal to the tallest it has been, released when the run ends.
+ *
+ * The min-height only applies when the turn shrinks, so it is never a frame late: the
+ * value was recorded while the turn grew.
+ */
+export function useTailSpacer(
+  viewport: HTMLDivElement | null,
+  pinIfFollowing: () => void,
+  active = false,
+): { lastTurnRef: (node: HTMLDivElement | null) => void } {
+  const lastTurn = React.useRef<HTMLDivElement | null>(null);
+  const observer = React.useRef<ResizeObserver | null>(null);
+  const activeRef = React.useRef(active);
+  activeRef.current = active;
+  const tallest = React.useRef(0);
+  const viewportSize = React.useRef('');
+
+  const measure = React.useCallback(() => {
+    const node = lastTurn.current;
+    if (!viewport || !node) return;
+    const size = `${viewport.clientWidth}:${viewport.clientHeight}`;
+    if (viewportSize.current !== size) { tallest.current = 0; viewportSize.current = size; }
+    let min = 0;
+    if (activeRef.current) {
+      tallest.current = Math.max(tallest.current, node.getBoundingClientRect().height);
+      min = Math.max(min, Math.floor(tallest.current));
+    } else tallest.current = 0;
+    const next = min > 0 ? `${min}px` : '';
+    if (node.style.minHeight !== next) {
+      node.style.minHeight = next;
+      pinIfFollowing();
+    }
+  }, [viewport, pinIfFollowing]);
+
+  React.useLayoutEffect(() => { measure(); }, [active, measure]);
+
+  React.useLayoutEffect(() => {
+    if (!viewport) return undefined;
+    const ro = new ResizeObserver(() => measure());
+    observer.current = ro;
+    ro.observe(viewport);
+    if (lastTurn.current) ro.observe(lastTurn.current);
+    measure();
+    return () => {
+      observer.current = null;
+      ro.disconnect();
+    };
+  }, [measure, viewport]);
+
+  /* A callback ref: each new turn becomes the last one, so the previous turn's min-height
+     is cleared and the observer moves to the new box. */
+  const lastTurnRef = React.useCallback((node: HTMLDivElement | null) => {
+    const previous = lastTurn.current;
+    if (previous && previous !== node) {
+      observer.current?.unobserve(previous);
+      previous.style.minHeight = '';
+      tallest.current = 0;
+    }
+    lastTurn.current = node;
+    if (node) observer.current?.observe(node);
+    measure();
+  }, [measure]);
+
+  return { lastTurnRef };
+}
+
+export function useStickToBottom(): StickToBottom {
+  /* The node is kept twice: the ref for synchronous reads in callbacks, the state so the
+     subscription below re-attaches when the viewport finally mounts. */
+  const viewportNode = React.useRef<HTMLDivElement | null>(null);
+  const [viewport, setViewport] = React.useState<HTMLDivElement | null>(null);
+  const viewportRef = React.useCallback((node: HTMLDivElement | null) => {
+    viewportNode.current = node;
+    setViewport(node);
+  }, []);
+  const contentNode = React.useRef<HTMLDivElement | null>(null);
+  const observer = React.useRef<ResizeObserver | null>(null);
+  /* Following lives in a ref, not state: the observer reads it every frame and needs the
+     current value, while state in its closure would be last frame's snapshot. */
+  const following = React.useRef(true);
+  const [atBottom, setAtBottom] = React.useState(true);
+
+  /* While gliding, the glide pins each frame; the observer must not jump it to the end. */
+  const glide = React.useRef<number | null>(null);
+  const pin = React.useCallback(() => {
+    const el = viewportNode.current;
+    if (glide.current != null) return;
+    // Overshoot and let the browser clamp to scrollHeight - clientHeight. Computing it
+    // ourselves is half a pixel short at fractional scaling (125% displays).
+    if (el) el.scrollTop = el.scrollHeight;
+  }, []);
+  const stopGlide = React.useCallback(() => {
+    if (glide.current != null) cancelAnimationFrame(glide.current);
+    glide.current = null;
+  }, []);
+
+  const scrollToBottom = React.useCallback((opts?: { smooth?: boolean }) => {
+    following.current = true;
+    setAtBottom(true);
+    stopGlide();
+    const el = viewportNode.current;
+    const reduced = typeof window !== 'undefined' && window.matchMedia?.('(prefers-reduced-motion: reduce)').matches;
+    if (!el || !opts?.smooth || reduced) { pin(); return; }
+    const from = el.scrollTop;
+    const started = performance.now();
+    const step = (now: number) => {
+      const k = Math.min(1, (now - started) / GLIDE_MS);
+      const eased = 1 - (1 - k) ** 3;
+      const target = el.scrollHeight - el.clientHeight;
+      if (!following.current) { glide.current = null; return; }
+      if (k >= 1) { glide.current = null; el.scrollTop = el.scrollHeight; return; }
+      el.scrollTop = from + (target - from) * eased;
+      glide.current = requestAnimationFrame(step);
+    };
+    glide.current = requestAnimationFrame(step);
+  }, [pin, stopGlide]);
+
+  const pinIfFollowing = React.useCallback(() => {
+    if (following.current) pin();
+  }, [pin]);
+
+  const skipPin = React.useRef(false);
+  const skipGen = React.useRef(0);
+  const skipNextPin = React.useCallback(() => {
+    skipPin.current = true;
+    following.current = false;
+    const gen = ++skipGen.current;
+    /* The content grows on the click frame and the spacer shrinks on the next, so both
+       observations are skipped. On repeated clicks only the last one counts. */
+    requestAnimationFrame(() => {
+      requestAnimationFrame(() => {
+        if (skipGen.current !== gen) return;
+        skipPin.current = false;
+        /* Still at the very bottom: nothing went below the view (the running turn's
+           min-height took the change), so keep following and hide "Jump to latest". */
+        const el = viewportNode.current;
+        if (el && el.scrollHeight - el.scrollTop - el.clientHeight <= 2) {
+          following.current = true;
+          setAtBottom(true);
+        }
+      });
+    });
+  }, []);
+
+  /* The content box can be swapped (empty state and conversation list), so a callback ref
+     moves the observer to the new box. `observe` fires once right away, which pins. */
+  const contentRef = React.useCallback((node: HTMLDivElement | null) => {
+    if (contentNode.current) observer.current?.unobserve(contentNode.current);
+    contentNode.current = node;
+    if (node) observer.current?.observe(node);
+  }, []);
+
+  /* Re-subscribes whenever the viewport changes (first mount or a replaced tree); that is
+     why `viewport` is a dependency. */
+  React.useLayoutEffect(() => {
+    const el = viewport;
+    if (!el) return undefined;
+
+    const nearBottom = () => el.scrollHeight - el.scrollTop - el.clientHeight <= NEAR_BOTTOM_PX;
+    let previousTop = el.scrollTop;
+    const sync = () => {
+      const near = nearBottom();
+      const top = el.scrollTop;
+      /* During a glide the bottom can move up (a turn collapsed) and scrollTop with it; that is not the user scrolling up */
+      if (glide.current == null && top < previousTop - 1 && el.scrollHeight - top - el.clientHeight > 2) following.current = false;
+      // Resizes and our own pin also emit scroll events. Only a downward user
+      // scroll all the way to the bottom resumes following after an upward wheel.
+      if (!following.current && top > previousTop && el.scrollHeight - top - el.clientHeight <= 2) {
+        following.current = true;
+      }
+      previousTop = top;
+      /* A collapse at the bottom clamps scrollTop; during the skip that is not leaving the bottom */
+      setAtBottom((following.current || skipPin.current) && near);
+    };
+    const release = () => {
+      // When the content does not scroll yet, a wheel up does nothing and does not release.
+      if (el.scrollHeight <= el.clientHeight + 1) return;
+      stopGlide();
+      following.current = false;
+      setAtBottom(false);
+    };
+
+    const onWheel = (e: WheelEvent) => {
+      if (e.deltaY < 0) release();
+    };
+    let lastTouchY = 0;
+    const onTouchStart = (e: TouchEvent) => {
+      lastTouchY = e.touches[0]?.clientY ?? 0;
+    };
+    const onTouchMove = (e: TouchEvent) => {
+      const y = e.touches[0]?.clientY ?? 0;
+      if (y > lastTouchY + 2) release();
+      lastTouchY = y;
+    };
+
+    el.addEventListener('scroll', sync, { passive: true });
+    el.addEventListener('wheel', onWheel, { passive: true });
+    el.addEventListener('touchstart', onTouchStart, { passive: true });
+    el.addEventListener('touchmove', onTouchMove, { passive: true });
+
+    const ro = new ResizeObserver(() => {
+      if (skipPin.current) {
+        /* Only update `atBottom`; do not resume following or clear the flag. This height
+           change came from a click, not from content growing; sync() would resume
+           following while still at the bottom, and the spacer frame would pin again. */
+        const near = el.scrollHeight - el.scrollTop - el.clientHeight <= NEAR_BOTTOM_PX;
+        setAtBottom((was) => (was === near ? was : near));
+        return;
+      }
+      if (following.current) pin();
+      /* Not following (a row was expanded): show "Jump to latest" once new content goes below the view */
+      else if (el.scrollHeight - el.scrollTop - el.clientHeight > NEAR_BOTTOM_PX) setAtBottom(false);
+    });
+    observer.current = ro;
+    ro.observe(el);
+    if (contentNode.current) ro.observe(contentNode.current);
+    pin();
+
+    return () => {
+      observer.current = null;
+      ro.disconnect();
+      el.removeEventListener('scroll', sync);
+      el.removeEventListener('wheel', onWheel);
+      el.removeEventListener('touchstart', onTouchStart);
+      el.removeEventListener('touchmove', onTouchMove);
+    };
+  }, [pin, stopGlide, viewport]);
+
+  return React.useMemo(
+    () => ({
+      viewportRef,
+      viewport,
+      contentRef,
+      atBottom,
+      scrollToBottom,
+      pinIfFollowing,
+      skipNextPin,
+    }),
+    [
+      viewportRef,
+      viewport,
+      contentRef,
+      atBottom,
+      scrollToBottom,
+      pinIfFollowing,
+      skipNextPin,
+    ],
+  );
+}