@stream-mdx/react 0.4.0 → 1.0.0

package/README.md

@@ -1,8 +1,8 @@
 # `@stream-mdx/react`
 
-React renderer for StreamMDX. Exposes the `<StreamingMarkdown />` component, scheduling/backpressure hooks, and the public types used by consumers.
+`@stream-mdx/react` is the renderer package for StreamMDX. It owns the React component surface, the renderer store, patch scheduling, server rendering helpers, and the packaged bottom-stick scroll component used by the docs/demo surfaces.
 
-Most apps should install `stream-mdx` instead of this package directly. Use `@stream-mdx/react` when you want the React surface without the unscoped wrapper.
+**Most apps should install [`stream-mdx`](../stream-mdx/README.md) instead.** Use this package directly when you want the React layer without the convenience wrapper.
 
 ## Install
 
@@ -10,19 +10,33 @@ Most apps should install `stream-mdx` instead of this package directly. Use `@st
 npm install @stream-mdx/react @stream-mdx/worker
 ```
 
-`react` and `react-dom` are peer dependencies.
+Peer dependencies:
 
-## Quickstart
+| Package | Range |
+| --- | --- |
+| `react` | `>=18.2.0` |
+| `react-dom` | `>=18.2.0` |
+
+## Primary Exports
 
-Copy the hosted worker bundle into your app’s static assets:
+| Export | Purpose |
+| --- | --- |
+| `@stream-mdx/react` | Main React surface including `<StreamingMarkdown />` |
+| `@stream-mdx/react/server` | Server/static render helpers |
+| `@stream-mdx/react/components` | Shared UI component exports |
+| `@stream-mdx/react/components/bottom-stick-scroll-area` | Packaged sticky-bottom scroll container |
+| `@stream-mdx/react/renderer` | Lower-level renderer exports |
+| `@stream-mdx/react/renderer/patch-commit-scheduler` | Scheduler implementation surface |
+| `@stream-mdx/react/renderer/store` | Renderer store surface |
+| `@stream-mdx/react/trusted-mdx` | Explicit trusted-MDX engine factory and pure contract types |
+
+## Quickstart
 
 ```bash
 mkdir -p public/workers
 cp node_modules/@stream-mdx/worker/dist/hosted/markdown-worker.js public/workers/markdown-worker.js
 ```
 
-Render streaming markdown from a client component:
-
 ```tsx
 "use client";
 
@@ -33,20 +47,131 @@ export function Demo({ text }: { text: string }) {
     <StreamingMarkdown
       text={text}
       worker="/workers/markdown-worker.js"
-      features={{ html: true, tables: true, math: true, mdx: true }}
-      mdxCompileMode="worker"
+      features={{ html: true, tables: true, math: true, footnotes: true }}
     />
   );
 }
 ```
 
-## Docs
+`engine` defaults to `"auto"` and bootstraps up to 4,096 accepted UTF-16 source units with the existing inline engine while worker setup and grammar prewarm are pending. Further source is deferred beyond that limit. `"worker"` requires a Worker; `"main"` runs parsing on the browser thread without a bootstrap cap. Engine setup runs after mounting, not during SSR. Use compiled snapshots and the server entry for server markup.
+
+### Rendering customization
+
+`components` replaces the removed renderer maps:
+
+- `inlineComponents` → `components["inline:<kind>"]` or `components["extension:<name>"]`
+- `htmlElements` → `components["html:<tag>"]`
+- `tableElements` → `components.table` wrappers or headless table views with `useTableBlock` / `useTableRows`
+- `codeRenderers` → `components.code` wrappers or headless code views; wrappers receive `metadata.language`, and `slots.actions` replaces native code actions. Mermaid diagrams use `engines.mermaid` from `createMermaidEngine()`
+- `mathRenderer` → presentation becomes a math wrapper/view in `components["inline:math"]`; TeX rendering uses `engines.math` (KaTeX remains the default)
+- `mdxComponents` → restricted `contentComponents` registrations, or trusted `contentPolicy="trusted-mdx"` with `engines.mdx`
+
+`features.math: false` disables math parsing. See the [public API](../../docs/PUBLIC_API.md) for HTML policy, restricted/trusted MDX, inert artifact fences, and optional finalized-block unified routing.
+
+`colorScheme` accepts `"light"`, `"dark"`, or `"system"` and sets the native root's `data-color-scheme`. System mode follows `prefers-color-scheme` with CSS only; when unset, a `.dark` ancestor keeps the existing class-based behavior. Native roots carry `data-stream-mdx` and `not-prose`, so enclosing typography-plugin selectors do not restyle native output and the optional Tailwind theme scopes native styles to that root.
+
+## Typical Uses
+
+| Use case | API |
+| --- | --- |
+| Browser/client rendering | `<StreamingMarkdown />` |
+| SSR / SSG / static export rendering | `MarkdownBlocksRenderer` from `@stream-mdx/react/server` |
+| Rich streaming/chat container | `BottomStickScrollArea` |
+| Advanced renderer internals | `renderer/store`, `renderer/patch-commit-scheduler` |
+
+### Server-side block rendering
+
+```tsx
+import { ComponentRegistry, MarkdownBlocksRenderer } from "@stream-mdx/react/server";
+
+return <MarkdownBlocksRenderer blocks={blocks} componentRegistry={new ComponentRegistry()} />;
+```
+
+Default math stays as authored TeX source on the server and on the client's first render. KaTeX loads after commit and replaces that source after mount, so cold and preloaded clients hydrate from the same markup.
+
+### Bottom-stick scroll area
+
+```tsx
+import { BottomStickScrollArea } from "@stream-mdx/react/components/bottom-stick-scroll-area";
+
+<BottomStickScrollArea className="h-[32rem]">{children}</BottomStickScrollArea>;
+```
+
+Behavior notes:
+
+- sticks to bottom while content appends
+- detaches on upward user scroll
+- supports smooth return-to-bottom behavior
+- honors `prefers-reduced-motion: reduce` with instant jumps and no jump-chrome transition
+- interrupts an active smooth return on wheel, touch, or scroll-key input without preventing native behavior
+- exposes debug hooks used by deterministic checks in the repo
+
+### Table row virtualization
+
+```tsx
+import { StreamingMarkdown } from "@stream-mdx/react";
+
+<StreamingMarkdown
+  text={content}
+  tableVirtualization={{
+    enabled: true,
+    minRows: 40,
+    estimatedRowHeight: 44,
+    overscan: 8,
+    maxHeight: "600px",
+  }}
+/>
+```
+
+Table virtualization is disabled by default. Only finalized tables meeting `minRows` virtualize after mounting in a browser and after the surrounding stream ends. SSR, unfinished tables, and active streams render every row.
+
+Virtualized tables retain native table elements, a sticky header, measured variable row heights, and `aria-hidden` spacer rows. The last row remains reachable by scrolling.
+When detached from the bottom, row measurements preserve the visible row and its pixel offset, including content partly covered by the sticky header. Scrolling chooses a new anchor; bottom attachment still follows measured tail growth.
+
+### Code viewport and printing
+
+Large native code blocks use a bounded reader viewport. The **Show full content** control mounts all authored lines while retaining the existing code wrapper and mounted native rows; toggling back restores the bounded window and reader anchor.
+
+`StreamingMarkdown` accepts `codeVirtualization?: Partial<VirtualizedCodeConfig>` to configure native code viewport presentation:
+
+```tsx
+<StreamingMarkdown text={content} codeVirtualization={{ followTail: true }} />
+```
+
+`followTail` defaults to `false`, preserving the reader position when code is appended. Set it to `true` to opt in to following appended rows while attached at the physical bottom (within 2px). An upward scroll of more than 1px detaches; returning within 2px reattaches. Changing this presentation config does not reset authored source or replace the native viewport; turning `followTail` off preserves the existing reader anchor and scroll position on a subsequent append.
+
+When a browser dispatches `beforeprint`, an eligible virtualized native code block temporarily mounts its full source and removes viewport clipping and height limits. `afterprint` restores the prior reader mode, scroll anchor, and native text selection without changing the manual full-content control.
+
+Print preparation mounts the whole block in the DOM, so print-time memory and layout work scale with the source length. Custom code renderers and server-rendered output control their own print behavior.
+
+Native whole-code copy/download uses cold authored source, preserving CR/LF and trailing blank lines rather than normalized display text. The test DOM exercises copy with an active selection and a Clipboard API stub; no physical browser or OS clipboard proof is claimed. Download shares the source action, but direct Blob browser proof remains pending. Native copied-status feedback cleanup prevents delayed updates after unmount.
+Each eligible virtualized table also exposes a "Show full content" toggle. It mounts every row only on request; toggling it again restores the bounded viewport without replacing the native table or changing the reader's scroll position.
+
+
+### Table controls
+
+Table controls are off by default. Enable Markdown copy or download for tables with `controls`:
+
+```tsx
+<StreamingMarkdown
+  text={content}
+  features={{ tables: true }}
+  controls={{ table: { copy: ["markdown"], download: ["markdown"] } }}
+/>
+```
+
+For native tables, Markdown copy and download use the table's authored source slice. They preserve spacing, escaped pipes, inline Markdown, and original line endings, and exclude the final row's line ending and any following document content. TSV and CSV remain cell-value transforms, not source-preserving Markdown.
+
+## When To Use This Package Directly
 
-- API reference: https://github.com/kmccleary3301/stream-mdx/blob/main/docs/PUBLIC_API.md
-- React integration guide: https://github.com/kmccleary3301/stream-mdx/blob/main/docs/REACT_INTEGRATION_GUIDE.md
-- Plugins & worker customization: https://github.com/kmccleary3301/stream-mdx/blob/main/docs/STREAMING_MARKDOWN_PLUGINS_COOKBOOK.md
-- Full docs site: https://kmccleary3301.github.io/stream-mdx/
+- You are shipping a library that wants `@stream-mdx/react` explicitly in `peerDependencies` or `dependencies`.
+- You need server rendering helpers without the convenience wrapper import path.
+- You are working on renderer internals and want the lower-level exports directly.
 
-## Addons
+## Documentation
 
-- `@stream-mdx/mermaid` (optional Mermaid diagram renderer)
+- [`../../docs/PUBLIC_API.md`](../../docs/PUBLIC_API.md)
+- [`../../docs/REACT_INTEGRATION_GUIDE.md`](../../docs/REACT_INTEGRATION_GUIDE.md)
+- [`../../docs/SECURITY_MODEL.md`](../../docs/SECURITY_MODEL.md)
+- [`../../docs/STREAMING_CORRECTNESS_CONTRACT.md`](../../docs/STREAMING_CORRECTNESS_CONTRACT.md)
+- Docs site: <https://stream-mdx.vercel.app/docs>

package/dist/blocks-renderer-DAOBFBfi.d.ts

@@ -0,0 +1,29 @@
+import { Block, UrlTransform } from '@stream-mdx/core';
+import React__default from 'react';
+import { l as ElementFilterOptions, d as ComponentRegistry, _ as NodePresentations, b as ControlsConfig, c as ControlsComponentProps, w as AnimatedProp, C as ContentComponentsMap, $ as MermaidEngine } from './index-D7dyyu3q.js';
+import { RendererStore } from './renderer/store.js';
+
+/**
+ * React component for rendering markdown blocks
+ */
+interface MarkdownBlocksRendererProps extends ElementFilterOptions {
+    blocks: ReadonlyArray<Block>;
+    componentRegistry?: ComponentRegistry;
+    className?: string;
+    style?: React__default.CSSProperties;
+    colorScheme?: "light" | "dark" | "system";
+    store?: RendererStore;
+    components?: NodePresentations;
+    urlTransform?: UrlTransform;
+    controls?: ControlsConfig;
+    controlsComponent?: React__default.ComponentType<ControlsComponentProps>;
+    animated?: AnimatedProp;
+    statusMessage?: string;
+    contentComponents?: ContentComponentsMap;
+    engines?: {
+        mermaid?: MermaidEngine;
+    };
+}
+declare const MarkdownBlocksRenderer: React__default.NamedExoticComponent<MarkdownBlocksRendererProps>;
+
+export { MarkdownBlocksRenderer as M, type MarkdownBlocksRendererProps as a };

package/dist/blocks-renderer-DQEL1kJW.d.cts

@@ -0,0 +1,29 @@
+import { Block, UrlTransform } from '@stream-mdx/core';
+import React__default from 'react';
+import { l as ElementFilterOptions, d as ComponentRegistry, _ as NodePresentations, b as ControlsConfig, c as ControlsComponentProps, w as AnimatedProp, C as ContentComponentsMap, $ as MermaidEngine } from './index-Cmne1yUK.cjs';
+import { RendererStore } from './renderer/store.cjs';
+
+/**
+ * React component for rendering markdown blocks
+ */
+interface MarkdownBlocksRendererProps extends ElementFilterOptions {
+    blocks: ReadonlyArray<Block>;
+    componentRegistry?: ComponentRegistry;
+    className?: string;
+    style?: React__default.CSSProperties;
+    colorScheme?: "light" | "dark" | "system";
+    store?: RendererStore;
+    components?: NodePresentations;
+    urlTransform?: UrlTransform;
+    controls?: ControlsConfig;
+    controlsComponent?: React__default.ComponentType<ControlsComponentProps>;
+    animated?: AnimatedProp;
+    statusMessage?: string;
+    contentComponents?: ContentComponentsMap;
+    engines?: {
+        mermaid?: MermaidEngine;
+    };
+}
+declare const MarkdownBlocksRenderer: React__default.NamedExoticComponent<MarkdownBlocksRendererProps>;
+
+export { MarkdownBlocksRenderer as M, type MarkdownBlocksRendererProps as a };

package/dist/components/bottom-stick-scroll-area.cjs

@@ -0,0 +1,268 @@
+"use client";
+"use strict";
+"use client";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: !0 });
+}, __copyProps = (to, from, except, desc) => {
+  if (from && typeof from == "object" || typeof from == "function")
+    for (let key of __getOwnPropNames(from))
+      !__hasOwnProp.call(to, key) && key !== except && __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: !0 }), mod);
+
+// src/components/bottom-stick-scroll-area.tsx
+var bottom_stick_scroll_area_exports = {};
+__export(bottom_stick_scroll_area_exports, {
+  BottomStickScrollArea: () => BottomStickScrollArea
+});
+module.exports = __toCommonJS(bottom_stick_scroll_area_exports);
+var import_react = require("react"), import_jsx_runtime = require("react/jsx-runtime"), EPS_BOTTOM_PX = 2, EPS_OVERFLOW_PX = 1, DETACH_SCROLL_DELTA_PX = 1, RETURN_MIN_MS = 180, RETURN_MAX_MS = 520, RETURN_PX_PER_MS = 2.2, RETURN_SETTLE_FRAMES = 2;
+function clamp01(value) {
+  return value < 0 ? 0 : value > 1 ? 1 : value;
+}
+function easeOutCubic(value) {
+  return 1 - (1 - value) ** 3;
+}
+function joinClasses(...parts) {
+  return parts.filter(Boolean).join(" ");
+}
+function measure(viewport) {
+  let scrollTop = viewport.scrollTop, scrollHeight = viewport.scrollHeight, clientHeight = viewport.clientHeight, maxScrollTop = Math.max(0, scrollHeight - clientHeight), distanceToBottom = Math.max(0, maxScrollTop - scrollTop), isOverflowing = scrollHeight > clientHeight + EPS_OVERFLOW_PX;
+  return { scrollTop, scrollHeight, clientHeight, maxScrollTop, distanceToBottom, isOverflowing };
+}
+function isEditableTarget(target) {
+  if (!(target instanceof Element)) return !1;
+  if (target.closest("input, textarea, select, [role='textbox']")) return !0;
+  let contentEditable = target.closest("[contenteditable]");
+  return contentEditable !== null && contentEditable.getAttribute("contenteditable")?.toLowerCase() !== "false";
+}
+function isScrollKeyIntent(event) {
+  if (event.defaultPrevented || isEditableTarget(event.target)) return !1;
+  switch (event.key) {
+    case "ArrowDown":
+    case "ArrowUp":
+    case "PageDown":
+    case "PageUp":
+    case "Home":
+    case "End":
+      return !0;
+    case " ":
+    case "Spacebar":
+      return event.target instanceof Element ? event.target.closest(
+        "button, input, summary, [role='button'], [role='checkbox'], [role='switch'], [role='radio'], [role='menuitem'], [role='menuitemcheckbox'], [role='menuitemradio']"
+      ) === null : !0;
+    default:
+      return !1;
+  }
+}
+function DefaultJumpButton({ canJump, jumpToBottom }) {
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+    "button",
+    {
+      type: "button",
+      onClick: jumpToBottom,
+      "aria-label": "Scroll to bottom",
+      style: {
+        pointerEvents: canJump ? "auto" : "none",
+        borderRadius: 9999,
+        border: "1px solid color-mix(in srgb, currentColor 20%, transparent)",
+        width: 40,
+        height: 40,
+        display: "grid",
+        placeItems: "center",
+        boxShadow: "0 8px 20px rgba(0,0,0,0.18)",
+        background: "color-mix(in srgb, var(--background, #fff) 92%, transparent)",
+        color: "var(--foreground, #111)",
+        cursor: canJump ? "pointer" : "default"
+      },
+      children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", { "aria-hidden": !0, children: "\u2193" })
+    }
+  );
+}
+function BottomStickScrollArea({
+  children,
+  className,
+  viewportClassName,
+  contentClassName,
+  showJumpToBottom = !0,
+  onDebugStateChange,
+  onModeChange,
+  debugDomAttributes = !1,
+  renderJumpToBottom,
+  jumpContainerClassName
+}) {
+  let viewportRef = (0, import_react.useRef)(null), contentRef = (0, import_react.useRef)(null), modeRef = (0, import_react.useRef)("STICKY_INSTANT"), [mode, setMode] = (0, import_react.useState)("STICKY_INSTANT"), [isOverflowing, setIsOverflowing] = (0, import_react.useState)(!1), [distanceToBottom, setDistanceToBottom] = (0, import_react.useState)(0), [prefersReducedMotion, setPrefersReducedMotion] = (0, import_react.useState)(!1), prefersReducedMotionRef = (0, import_react.useRef)(!1), prevScrollTopRef = (0, import_react.useRef)(0), lastProgrammaticWriteRef = (0, import_react.useRef)(null), programmaticWriteCountRef = (0, import_react.useRef)(0), pendingStickRafRef = (0, import_react.useRef)(null), stickRequestedRef = (0, import_react.useRef)(!1), returnRafRef = (0, import_react.useRef)(null), returnAnimRef = (0, import_react.useRef)(null), setModeBoth = (0, import_react.useCallback)(
+    (next) => {
+      modeRef.current = next, setMode(next), onModeChange?.(next);
+    },
+    [onModeChange]
+  ), updateDebug = (0, import_react.useCallback)(() => {
+    let viewport = viewportRef.current;
+    if (!viewport) return;
+    let m = measure(viewport);
+    debugDomAttributes && (viewport.dataset.stickyMode = modeRef.current, viewport.dataset.distanceToBottom = String(m.distanceToBottom), viewport.dataset.isOverflowing = m.isOverflowing ? "1" : "0", viewport.dataset.programmaticWrites = String(programmaticWriteCountRef.current)), onDebugStateChange?.({
+      mode: modeRef.current,
+      isOverflowing: m.isOverflowing,
+      distanceToBottom: m.distanceToBottom,
+      scrollTop: m.scrollTop,
+      maxScrollTop: m.maxScrollTop,
+      scrollHeight: m.scrollHeight,
+      clientHeight: m.clientHeight,
+      programmaticWrites: programmaticWriteCountRef.current
+    }), setDistanceToBottom(
+      (previous) => Math.abs(previous - m.distanceToBottom) <= 0.1 ? previous : m.distanceToBottom
+    );
+  }, [debugDomAttributes, onDebugStateChange]), writeScrollTop = (0, import_react.useCallback)((nextTop) => {
+    let viewport = viewportRef.current;
+    viewport && (viewport.scrollTop = nextTop, programmaticWriteCountRef.current += 1, lastProgrammaticWriteRef.current = { at: performance.now(), top: nextTop });
+  }, []), cancelPendingStick = (0, import_react.useCallback)(() => {
+    pendingStickRafRef.current !== null && (cancelAnimationFrame(pendingStickRafRef.current), pendingStickRafRef.current = null), stickRequestedRef.current = !1;
+  }, []), cancelReturn = (0, import_react.useCallback)(() => {
+    returnRafRef.current !== null && (cancelAnimationFrame(returnRafRef.current), returnRafRef.current = null), returnAnimRef.current = null;
+  }, []), handleReducedMotionChange = (0, import_react.useCallback)(
+    (matches) => {
+      if (prefersReducedMotionRef.current !== matches && (prefersReducedMotionRef.current = matches, setPrefersReducedMotion(matches)), !matches || modeRef.current !== "RETURNING_SMOOTH") return;
+      cancelPendingStick(), cancelReturn(), setModeBoth("STICKY_INSTANT");
+      let viewport = viewportRef.current;
+      viewport && (writeScrollTop(measure(viewport).maxScrollTop), prevScrollTopRef.current = viewport.scrollTop), updateDebug();
+    },
+    [cancelPendingStick, cancelReturn, setModeBoth, updateDebug, writeScrollTop]
+  ), reducedMotionChangeHandlerRef = (0, import_react.useRef)(handleReducedMotionChange);
+  reducedMotionChangeHandlerRef.current = handleReducedMotionChange;
+  let interruptReturnForUserIntent = (0, import_react.useCallback)(() => {
+    modeRef.current === "RETURNING_SMOOTH" && (cancelPendingStick(), cancelReturn(), setModeBoth("DETACHED"), updateDebug());
+  }, [cancelPendingStick, cancelReturn, setModeBoth, updateDebug]), onViewportKeyDown = (0, import_react.useCallback)(
+    (event) => {
+      isScrollKeyIntent(event) && interruptReturnForUserIntent();
+    },
+    [interruptReturnForUserIntent]
+  ), stickToBottomInstant = (0, import_react.useCallback)(() => {
+    let viewport = viewportRef.current;
+    viewport && (stickRequestedRef.current = !0, pendingStickRafRef.current === null && (pendingStickRafRef.current = requestAnimationFrame(() => {
+      if (pendingStickRafRef.current = null, !stickRequestedRef.current || (stickRequestedRef.current = !1, modeRef.current !== "STICKY_INSTANT")) return;
+      let m = measure(viewport);
+      writeScrollTop(m.maxScrollTop), updateDebug();
+    })));
+  }, [updateDebug, writeScrollTop]), startReturnToBottomSmooth = (0, import_react.useCallback)(() => {
+    let viewport = viewportRef.current;
+    if (!viewport) return;
+    if (prefersReducedMotionRef.current) {
+      cancelPendingStick(), cancelReturn(), setModeBoth("STICKY_INSTANT"), writeScrollTop(measure(viewport).maxScrollTop), prevScrollTopRef.current = viewport.scrollTop, updateDebug();
+      return;
+    }
+    cancelPendingStick(), cancelReturn();
+    let initial = measure(viewport);
+    if (initial.distanceToBottom <= EPS_BOTTOM_PX) {
+      setModeBoth("STICKY_INSTANT"), stickToBottomInstant(), updateDebug();
+      return;
+    }
+    let durationMs = Math.max(
+      RETURN_MIN_MS,
+      Math.min(RETURN_MAX_MS, initial.distanceToBottom / RETURN_PX_PER_MS)
+    );
+    returnAnimRef.current = {
+      startTime: performance.now(),
+      startTop: initial.scrollTop,
+      durationMs,
+      settleFrames: 0
+    }, setModeBoth("RETURNING_SMOOTH");
+    let tick = (now) => {
+      let viewportCurrent = viewportRef.current, anim = returnAnimRef.current;
+      if (!viewportCurrent || !anim || modeRef.current !== "RETURNING_SMOOTH") {
+        cancelReturn();
+        return;
+      }
+      let before = measure(viewportCurrent), progress = clamp01((now - anim.startTime) / anim.durationMs), eased = easeOutCubic(progress), targetBottom = before.maxScrollTop, nextTop = anim.startTop + (targetBottom - anim.startTop) * eased;
+      nextTop < before.scrollTop && (nextTop = before.scrollTop), writeScrollTop(nextTop), measure(viewportCurrent).distanceToBottom <= EPS_BOTTOM_PX ? anim.settleFrames += 1 : anim.settleFrames = 0;
+      let doneByTime = progress >= 1, doneBySettle = anim.settleFrames >= RETURN_SETTLE_FRAMES && progress >= 0.6;
+      if (doneByTime && doneBySettle) {
+        cancelReturn(), setModeBoth("STICKY_INSTANT"), stickToBottomInstant(), updateDebug();
+        return;
+      }
+      updateDebug(), returnRafRef.current = requestAnimationFrame(tick);
+    };
+    returnRafRef.current = requestAnimationFrame(tick);
+  }, [cancelPendingStick, cancelReturn, setModeBoth, stickToBottomInstant, updateDebug, writeScrollTop]), onViewportScroll = (0, import_react.useCallback)(
+    (event) => {
+      let viewport = event.currentTarget, m = measure(viewport);
+      setIsOverflowing((previous) => previous === m.isOverflowing ? previous : m.isOverflowing);
+      let previousTop = prevScrollTopRef.current, delta = m.scrollTop - previousTop, lastWrite = lastProgrammaticWriteRef.current, isLikelyOwnWrite = lastWrite !== null && performance.now() - lastWrite.at < 60 && lastWrite !== null && Math.abs(m.scrollTop - lastWrite.top) <= 2;
+      modeRef.current === "RETURNING_SMOOTH" ? !isLikelyOwnWrite && delta < -DETACH_SCROLL_DELTA_PX && (cancelReturn(), setModeBoth("DETACHED")) : modeRef.current === "STICKY_INSTANT" ? !isLikelyOwnWrite && delta < -DETACH_SCROLL_DELTA_PX && m.isOverflowing && (cancelPendingStick(), setModeBoth("DETACHED")) : modeRef.current === "DETACHED" && m.distanceToBottom <= EPS_BOTTOM_PX && (setModeBoth("STICKY_INSTANT"), stickToBottomInstant()), prevScrollTopRef.current = m.scrollTop, updateDebug();
+    },
+    [cancelPendingStick, cancelReturn, setModeBoth, stickToBottomInstant, updateDebug]
+  );
+  (0, import_react.useEffect)(() => {
+    let viewport = viewportRef.current, content = contentRef.current;
+    if (!viewport || !content) return;
+    let observer = new ResizeObserver(() => {
+      let m = measure(viewport);
+      setIsOverflowing((previous) => previous === m.isOverflowing ? previous : m.isOverflowing), modeRef.current === "STICKY_INSTANT" && stickToBottomInstant(), updateDebug();
+    });
+    return observer.observe(content), observer.observe(viewport), () => observer.disconnect();
+  }, [stickToBottomInstant, updateDebug]), (0, import_react.useLayoutEffect)(() => {
+    let viewport = viewportRef.current;
+    if (!viewport) return;
+    setModeBoth("STICKY_INSTANT");
+    let initial = measure(viewport);
+    writeScrollTop(initial.maxScrollTop), prevScrollTopRef.current = viewport.scrollTop, setIsOverflowing(initial.isOverflowing), setDistanceToBottom(initial.distanceToBottom), updateDebug();
+  }, [setModeBoth, updateDebug, writeScrollTop]), (0, import_react.useLayoutEffect)(() => {
+    if (typeof window > "u" || typeof window.matchMedia != "function") return;
+    let mediaQuery = window.matchMedia("(prefers-reduced-motion: reduce)"), onChange = () => reducedMotionChangeHandlerRef.current(mediaQuery.matches);
+    return onChange(), typeof mediaQuery.addEventListener == "function" ? (mediaQuery.addEventListener("change", onChange), () => mediaQuery.removeEventListener("change", onChange)) : (mediaQuery.addListener(onChange), () => mediaQuery.removeListener(onChange));
+  }, []), (0, import_react.useEffect)(() => () => {
+    cancelPendingStick(), cancelReturn();
+  }, [cancelPendingStick, cancelReturn]);
+  let canJump = isOverflowing && mode === "DETACHED", jumpButton = renderJumpToBottom?.({
+    mode,
+    canJump,
+    isOverflowing,
+    distanceToBottom,
+    jumpToBottom: startReturnToBottomSmooth
+  }) ?? /* @__PURE__ */ (0, import_jsx_runtime.jsx)(DefaultJumpButton, { canJump, jumpToBottom: startReturnToBottomSmooth }), jumpContainerClassNameBase = "pointer-events-none absolute z-20", jumpContainerStyle = {
+    position: "absolute",
+    zIndex: 20,
+    left: 0,
+    right: 0,
+    bottom: 12,
+    display: "flex",
+    justifyContent: "center",
+    opacity: canJump ? 1 : 0,
+    transform: prefersReducedMotion ? "none" : canJump ? "translateY(0px)" : "translateY(4px)",
+    transition: prefersReducedMotion ? "none" : "opacity 150ms ease, transform 150ms ease",
+    pointerEvents: "none"
+  };
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { className: joinClasses("relative h-full w-full overflow-hidden", className), children: [
+    /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+      "div",
+      {
+        ref: viewportRef,
+        className: joinClasses("h-full w-full overflow-auto", viewportClassName),
+        onScroll: onViewportScroll,
+        onWheel: interruptReturnForUserIntent,
+        onTouchStart: interruptReturnForUserIntent,
+        onKeyDown: onViewportKeyDown,
+        "data-testid": "sticky-scroll-viewport",
+        children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { ref: contentRef, className: joinClasses("flex min-h-full w-full flex-col", contentClassName), children })
+      }
+    ),
+    showJumpToBottom ? /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+      "div",
+      {
+        className: joinClasses(jumpContainerClassNameBase, jumpContainerClassName),
+        style: jumpContainerStyle,
+        "aria-hidden": !canJump,
+        children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { className: canJump ? "pointer-events-auto" : "pointer-events-none", children: jumpButton })
+      }
+    ) : null
+  ] });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BottomStickScrollArea
+});

package/dist/components/bottom-stick-scroll-area.d.cts

@@ -0,0 +1,36 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+
+type BottomStickMode = "STICKY_INSTANT" | "DETACHED" | "RETURNING_SMOOTH";
+type BottomStickDebugState = {
+    mode: BottomStickMode;
+    isOverflowing: boolean;
+    distanceToBottom: number;
+    scrollTop: number;
+    maxScrollTop: number;
+    scrollHeight: number;
+    clientHeight: number;
+    programmaticWrites: number;
+};
+type BottomStickJumpButtonRenderState = {
+    mode: BottomStickMode;
+    canJump: boolean;
+    isOverflowing: boolean;
+    distanceToBottom: number;
+    jumpToBottom: () => void;
+};
+type BottomStickScrollAreaProps = {
+    children: ReactNode;
+    className?: string;
+    viewportClassName?: string;
+    contentClassName?: string;
+    showJumpToBottom?: boolean;
+    onDebugStateChange?: (state: BottomStickDebugState) => void;
+    onModeChange?: (mode: BottomStickMode) => void;
+    debugDomAttributes?: boolean;
+    renderJumpToBottom?: (state: BottomStickJumpButtonRenderState) => ReactNode;
+    jumpContainerClassName?: string;
+};
+declare function BottomStickScrollArea({ children, className, viewportClassName, contentClassName, showJumpToBottom, onDebugStateChange, onModeChange, debugDomAttributes, renderJumpToBottom, jumpContainerClassName, }: BottomStickScrollAreaProps): react_jsx_runtime.JSX.Element;
+
+export { type BottomStickDebugState, type BottomStickJumpButtonRenderState, type BottomStickMode, BottomStickScrollArea, type BottomStickScrollAreaProps };

package/dist/components/bottom-stick-scroll-area.d.ts

@@ -0,0 +1,36 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+
+type BottomStickMode = "STICKY_INSTANT" | "DETACHED" | "RETURNING_SMOOTH";
+type BottomStickDebugState = {
+    mode: BottomStickMode;
+    isOverflowing: boolean;
+    distanceToBottom: number;
+    scrollTop: number;
+    maxScrollTop: number;
+    scrollHeight: number;
+    clientHeight: number;
+    programmaticWrites: number;
+};
+type BottomStickJumpButtonRenderState = {
+    mode: BottomStickMode;
+    canJump: boolean;
+    isOverflowing: boolean;
+    distanceToBottom: number;
+    jumpToBottom: () => void;
+};
+type BottomStickScrollAreaProps = {
+    children: ReactNode;
+    className?: string;
+    viewportClassName?: string;
+    contentClassName?: string;
+    showJumpToBottom?: boolean;
+    onDebugStateChange?: (state: BottomStickDebugState) => void;
+    onModeChange?: (mode: BottomStickMode) => void;
+    debugDomAttributes?: boolean;
+    renderJumpToBottom?: (state: BottomStickJumpButtonRenderState) => ReactNode;
+    jumpContainerClassName?: string;
+};
+declare function BottomStickScrollArea({ children, className, viewportClassName, contentClassName, showJumpToBottom, onDebugStateChange, onModeChange, debugDomAttributes, renderJumpToBottom, jumpContainerClassName, }: BottomStickScrollAreaProps): react_jsx_runtime.JSX.Element;
+
+export { type BottomStickDebugState, type BottomStickJumpButtonRenderState, type BottomStickMode, BottomStickScrollArea, type BottomStickScrollAreaProps };