@stream-mdx/react 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -1,13 +1,23 @@
 # @stream-mdx/react
 
-## 0.1.1
+## 0.5.0
+
+### Minor Changes
+
+- Promote the current hardening and product-surface tranche as `0.5.0`.
+
+  This release rolls up:
+
+  - renderer/store correctness hardening
+  - seeded smoke and scheduler-parity release discipline
+  - benchmark methodology and comparison cleanup
+  - docs, showcase, and TUI/product surface maturation
 
 ### Patch Changes
 
-- Refine streaming scheduling and list layout, add worker append batching/debug state support, and refresh docs/README examples.
 - Updated dependencies
-  - @stream-mdx/core@0.1.1
-  - @stream-mdx/worker@0.1.1
+  - @stream-mdx/core@0.5.0
+  - @stream-mdx/worker@0.5.0
 
 ## 0.1.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,34 @@ 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/mdx-client` | MDX client helpers |
+| `@stream-mdx/react/mdx-coordinator` | MDX coordination helpers |
+
+## 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,19 +48,55 @@ export function Demo({ text }: { text: string }) {
     <StreamingMarkdown
       text={text}
       worker="/workers/markdown-worker.js"
-      features={{ html: true, tables: true, math: true, mdx: true }}
+      features={{ html: true, tables: true, math: true, mdx: true, footnotes: true }}
       mdxCompileMode="worker"
     />
   );
 }
 ```
 
-## Docs
+## 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()} />;
+```
+
+### 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
+- exposes debug hooks used by deterministic checks in the repo
+
+## When To Use This Package Directly
 
-- API reference: `docs/PUBLIC_API.md`
-- React integration guide: `docs/REACT_INTEGRATION_GUIDE.md`
-- Plugins & worker customization: `docs/STREAMING_MARKDOWN_PLUGINS_COOKBOOK.md`
+- 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/components/bottom-stick-scroll-area.cjs

@@ -0,0 +1,344 @@
+"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: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__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: true }), 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");
+var import_jsx_runtime = require("react/jsx-runtime");
+var EPS_BOTTOM_PX = 2;
+var EPS_OVERFLOW_PX = 1;
+var DETACH_SCROLL_DELTA_PX = 1;
+var RETURN_MIN_MS = 180;
+var RETURN_MAX_MS = 520;
+var RETURN_PX_PER_MS = 2.2;
+var RETURN_SETTLE_FRAMES = 2;
+function clamp01(value) {
+  if (value < 0) return 0;
+  if (value > 1) return 1;
+  return value;
+}
+function easeOutCubic(value) {
+  return 1 - (1 - value) ** 3;
+}
+function joinClasses(...parts) {
+  return parts.filter(Boolean).join(" ");
+}
+function measure(viewport) {
+  const scrollTop = viewport.scrollTop;
+  const scrollHeight = viewport.scrollHeight;
+  const clientHeight = viewport.clientHeight;
+  const maxScrollTop = Math.max(0, scrollHeight - clientHeight);
+  const distanceToBottom = Math.max(0, maxScrollTop - scrollTop);
+  const isOverflowing = scrollHeight > clientHeight + EPS_OVERFLOW_PX;
+  return { scrollTop, scrollHeight, clientHeight, maxScrollTop, distanceToBottom, isOverflowing };
+}
+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": true, children: "\u2193" })
+    }
+  );
+}
+function BottomStickScrollArea({
+  children,
+  className,
+  viewportClassName,
+  contentClassName,
+  showJumpToBottom = true,
+  onDebugStateChange,
+  onModeChange,
+  debugDomAttributes = false,
+  renderJumpToBottom,
+  jumpContainerClassName
+}) {
+  const viewportRef = (0, import_react.useRef)(null);
+  const contentRef = (0, import_react.useRef)(null);
+  const modeRef = (0, import_react.useRef)("STICKY_INSTANT");
+  const [mode, setMode] = (0, import_react.useState)("STICKY_INSTANT");
+  const [isOverflowing, setIsOverflowing] = (0, import_react.useState)(false);
+  const [distanceToBottom, setDistanceToBottom] = (0, import_react.useState)(0);
+  const prevScrollTopRef = (0, import_react.useRef)(0);
+  const lastProgrammaticWriteRef = (0, import_react.useRef)(null);
+  const programmaticWriteCountRef = (0, import_react.useRef)(0);
+  const pendingStickRafRef = (0, import_react.useRef)(null);
+  const stickRequestedRef = (0, import_react.useRef)(false);
+  const returnRafRef = (0, import_react.useRef)(null);
+  const returnAnimRef = (0, import_react.useRef)(null);
+  const setModeBoth = (0, import_react.useCallback)(
+    (next) => {
+      modeRef.current = next;
+      setMode(next);
+      onModeChange?.(next);
+    },
+    [onModeChange]
+  );
+  const updateDebug = (0, import_react.useCallback)(() => {
+    const viewport = viewportRef.current;
+    if (!viewport) return;
+    const m = measure(viewport);
+    if (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]);
+  const writeScrollTop = (0, import_react.useCallback)((nextTop) => {
+    const viewport = viewportRef.current;
+    if (!viewport) return;
+    viewport.scrollTop = nextTop;
+    programmaticWriteCountRef.current += 1;
+    lastProgrammaticWriteRef.current = { at: performance.now(), top: nextTop };
+  }, []);
+  const cancelPendingStick = (0, import_react.useCallback)(() => {
+    if (pendingStickRafRef.current !== null) {
+      cancelAnimationFrame(pendingStickRafRef.current);
+      pendingStickRafRef.current = null;
+    }
+    stickRequestedRef.current = false;
+  }, []);
+  const cancelReturn = (0, import_react.useCallback)(() => {
+    if (returnRafRef.current !== null) {
+      cancelAnimationFrame(returnRafRef.current);
+      returnRafRef.current = null;
+    }
+    returnAnimRef.current = null;
+  }, []);
+  const stickToBottomInstant = (0, import_react.useCallback)(() => {
+    const viewport = viewportRef.current;
+    if (!viewport) return;
+    stickRequestedRef.current = true;
+    if (pendingStickRafRef.current !== null) return;
+    pendingStickRafRef.current = requestAnimationFrame(() => {
+      pendingStickRafRef.current = null;
+      if (!stickRequestedRef.current) return;
+      stickRequestedRef.current = false;
+      if (modeRef.current !== "STICKY_INSTANT") return;
+      const m = measure(viewport);
+      writeScrollTop(m.maxScrollTop);
+      updateDebug();
+    });
+  }, [updateDebug, writeScrollTop]);
+  const startReturnToBottomSmooth = (0, import_react.useCallback)(() => {
+    const viewport = viewportRef.current;
+    if (!viewport) return;
+    cancelPendingStick();
+    cancelReturn();
+    const initial = measure(viewport);
+    if (initial.distanceToBottom <= EPS_BOTTOM_PX) {
+      setModeBoth("STICKY_INSTANT");
+      stickToBottomInstant();
+      updateDebug();
+      return;
+    }
+    const 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");
+    const tick = (now) => {
+      const viewportCurrent = viewportRef.current;
+      const anim = returnAnimRef.current;
+      if (!viewportCurrent || !anim || modeRef.current !== "RETURNING_SMOOTH") {
+        cancelReturn();
+        return;
+      }
+      const before = measure(viewportCurrent);
+      const progress = clamp01((now - anim.startTime) / anim.durationMs);
+      const eased = easeOutCubic(progress);
+      const targetBottom = before.maxScrollTop;
+      let nextTop = anim.startTop + (targetBottom - anim.startTop) * eased;
+      if (nextTop < before.scrollTop) {
+        nextTop = before.scrollTop;
+      }
+      writeScrollTop(nextTop);
+      const after = measure(viewportCurrent);
+      if (after.distanceToBottom <= EPS_BOTTOM_PX) {
+        anim.settleFrames += 1;
+      } else {
+        anim.settleFrames = 0;
+      }
+      const doneByTime = progress >= 1;
+      const 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]);
+  const onViewportScroll = (0, import_react.useCallback)(
+    (event) => {
+      const viewport = event.currentTarget;
+      const m = measure(viewport);
+      setIsOverflowing((previous) => previous === m.isOverflowing ? previous : m.isOverflowing);
+      const previousTop = prevScrollTopRef.current;
+      const delta = m.scrollTop - previousTop;
+      const lastWrite = lastProgrammaticWriteRef.current;
+      const wroteRecently = lastWrite !== null && performance.now() - lastWrite.at < 60;
+      const isLikelyOwnWrite = wroteRecently && lastWrite !== null && Math.abs(m.scrollTop - lastWrite.top) <= 2;
+      if (modeRef.current === "RETURNING_SMOOTH") {
+        if (!isLikelyOwnWrite && delta < -DETACH_SCROLL_DELTA_PX) {
+          cancelReturn();
+          setModeBoth("DETACHED");
+        }
+      } else if (modeRef.current === "STICKY_INSTANT") {
+        if (!isLikelyOwnWrite && delta < -DETACH_SCROLL_DELTA_PX && m.isOverflowing) {
+          cancelPendingStick();
+          setModeBoth("DETACHED");
+        }
+      } else if (modeRef.current === "DETACHED") {
+        if (m.distanceToBottom <= EPS_BOTTOM_PX) {
+          setModeBoth("STICKY_INSTANT");
+          stickToBottomInstant();
+        }
+      }
+      prevScrollTopRef.current = m.scrollTop;
+      updateDebug();
+    },
+    [cancelPendingStick, cancelReturn, setModeBoth, stickToBottomInstant, updateDebug]
+  );
+  (0, import_react.useEffect)(() => {
+    const viewport = viewportRef.current;
+    const content = contentRef.current;
+    if (!viewport || !content) return;
+    const observer = new ResizeObserver(() => {
+      const m = measure(viewport);
+      setIsOverflowing((previous) => previous === m.isOverflowing ? previous : m.isOverflowing);
+      if (modeRef.current === "STICKY_INSTANT") {
+        stickToBottomInstant();
+      }
+      updateDebug();
+    });
+    observer.observe(content);
+    observer.observe(viewport);
+    return () => observer.disconnect();
+  }, [stickToBottomInstant, updateDebug]);
+  (0, import_react.useLayoutEffect)(() => {
+    const viewport = viewportRef.current;
+    if (!viewport) return;
+    setModeBoth("STICKY_INSTANT");
+    const initial = measure(viewport);
+    writeScrollTop(initial.maxScrollTop);
+    prevScrollTopRef.current = viewport.scrollTop;
+    setIsOverflowing(initial.isOverflowing);
+    setDistanceToBottom(initial.distanceToBottom);
+    updateDebug();
+  }, [setModeBoth, updateDebug, writeScrollTop]);
+  (0, import_react.useEffect)(() => {
+    return () => {
+      cancelPendingStick();
+      cancelReturn();
+    };
+  }, [cancelPendingStick, cancelReturn]);
+  const canJump = isOverflowing && mode === "DETACHED";
+  const jumpButton = renderJumpToBottom?.({
+    mode,
+    canJump,
+    isOverflowing,
+    distanceToBottom,
+    jumpToBottom: startReturnToBottomSmooth
+  }) ?? /* @__PURE__ */ (0, import_jsx_runtime.jsx)(DefaultJumpButton, { canJump, jumpToBottom: startReturnToBottomSmooth });
+  const jumpContainerClassNameBase = "pointer-events-none absolute z-20";
+  const jumpContainerStyle = {
+    position: "absolute",
+    zIndex: 20,
+    left: 0,
+    right: 0,
+    bottom: 12,
+    display: "flex",
+    justifyContent: "center",
+    opacity: canJump ? 1 : 0,
+    transform: canJump ? "translateY(0px)" : "translateY(4px)",
+    transition: "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,
+        "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 };