@develemit/web-hooks 0.4.0 → 0.5.0

package/dist/virtual-list.cjs

@@ -0,0 +1,499 @@
+"use client";
+"use strict";
+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/virtual-list/index.ts
+var virtual_list_exports = {};
+__export(virtual_list_exports, {
+  MAX_REALIGN_FRAMES: () => MAX_REALIGN_FRAMES,
+  downloadText: () => downloadText,
+  initialVisibleCount: () => initialVisibleCount,
+  logToText: () => logToText,
+  measuredOrEstimate: () => measuredOrEstimate,
+  shouldRealign: () => shouldRealign,
+  targetOffset: () => targetOffset,
+  useVirtualList: () => useVirtualList,
+  useVirtualLog: () => useVirtualLog
+});
+module.exports = __toCommonJS(virtual_list_exports);
+
+// src/virtual-list/use-virtual-list.ts
+var import_react = require("react");
+var import_react_virtual = require("@tanstack/react-virtual");
+
+// src/virtual-list/measure.ts
+var MAX_REALIGN_FRAMES = 3;
+function measuredOrEstimate(measured, estimate) {
+  return measured !== void 0 && measured > 0 ? measured : estimate;
+}
+function targetOffset(align, itemStart, itemSize, viewportSize) {
+  if (align === "end") return itemStart + itemSize - viewportSize;
+  if (align === "center") return itemStart + itemSize / 2 - viewportSize / 2;
+  return itemStart;
+}
+function shouldRealign({ align, itemStart, itemSize, scrollOffset, viewportSize, frame, maxFrames = MAX_REALIGN_FRAMES }) {
+  if (frame >= maxFrames) return false;
+  if (align === "auto") {
+    return itemStart < scrollOffset || itemStart + itemSize > scrollOffset + viewportSize;
+  }
+  const want = Math.max(0, targetOffset(align, itemStart, itemSize, viewportSize));
+  return Math.abs(scrollOffset - want) > 1;
+}
+function initialVisibleCount(count, initialCount) {
+  return Math.min(count, Math.max(0, initialCount));
+}
+
+// src/virtual-list/use-virtual-list.ts
+var ESTIMATED_ROW_FOR_SSR = 30;
+function useVirtualList(options) {
+  const {
+    count,
+    estimateSize,
+    scrollRef,
+    windowScroll: scrollsWindow = false,
+    scrollMargin = 0,
+    overscan = 10,
+    measure = true,
+    getItemKey,
+    initialCount = 30
+  } = options;
+  const frameRef = (0, import_react.useRef)(null);
+  const virtualizer = (0, import_react_virtual.useVirtualizer)({
+    count,
+    estimateSize,
+    overscan,
+    scrollMargin,
+    getScrollElement: () => scrollsWindow ? typeof window === "undefined" ? null : window : scrollRef?.current ?? null,
+    ...scrollsWindow ? {
+      observeElementRect: import_react_virtual.observeWindowRect,
+      observeElementOffset: import_react_virtual.observeWindowOffset,
+      scrollToFn: import_react_virtual.windowScroll,
+      initialOffset: () => typeof window === "undefined" ? 0 : window.scrollY
+    } : {},
+    // Seeds a viewport so the server render and first paint include rows.
+    initialRect: { width: 0, height: initialCount * ESTIMATED_ROW_FOR_SSR },
+    ...getItemKey ? { getItemKey } : {},
+    ...measure ? {
+      measureElement: (el, entry, instance) => {
+        const height = entry?.borderBoxSize?.[0]?.blockSize ?? el.getBoundingClientRect().height;
+        const index = Number(el.dataset.index);
+        const estimate = Number.isNaN(index) ? 0 : instance.options.estimateSize(index);
+        return measuredOrEstimate(height, estimate);
+      }
+    } : {}
+  });
+  const cancelRealign = (0, import_react.useCallback)(() => {
+    if (frameRef.current !== null && typeof cancelAnimationFrame === "function") cancelAnimationFrame(frameRef.current);
+    frameRef.current = null;
+  }, []);
+  (0, import_react.useEffect)(() => cancelRealign, [cancelRealign]);
+  const scrollToIndex = (0, import_react.useCallback)(
+    (index, { align = "auto" } = {}) => {
+      cancelRealign();
+      const last = Math.max(0, count - 1);
+      const target = Math.max(0, Math.min(index, last));
+      virtualizer.scrollToIndex(target, { align });
+      if (typeof requestAnimationFrame !== "function") return;
+      let frame = 0;
+      const check = () => {
+        frameRef.current = null;
+        const item = virtualizer.measurementsCache[target];
+        const offset = virtualizer.scrollOffset;
+        const viewport = virtualizer.scrollRect?.height;
+        if (!item || offset === null || !viewport) return;
+        const input = { align, itemStart: item.start - scrollMargin, itemSize: item.size, scrollOffset: offset - scrollMargin, viewportSize: viewport, frame };
+        if (!shouldRealign(input)) return;
+        frame += 1;
+        virtualizer.scrollToIndex(target, { align });
+        frameRef.current = requestAnimationFrame(check);
+      };
+      frameRef.current = requestAnimationFrame(check);
+    },
+    [virtualizer, count, scrollMargin, cancelRealign]
+  );
+  const scrollToOffset = (0, import_react.useCallback)((offset) => virtualizer.scrollToOffset(offset), [virtualizer]);
+  const rendered = virtualizer.getVirtualItems();
+  const items = rendered.map((v) => ({ index: v.index, key: v.key, start: v.start - scrollMargin, size: v.size }));
+  const fallback = items.length === 0 && count > 0 ? initialVisibleCount(count, initialCount) : 0;
+  if (fallback > 0) {
+    let start = 0;
+    for (let i = 0; i < fallback; i++) {
+      const size = estimateSize(i);
+      items.push({ index: i, key: getItemKey ? getItemKey(i) : i, start, size });
+      start += size;
+    }
+  }
+  return {
+    items,
+    totalSize: virtualizer.getTotalSize(),
+    measureRef: measure ? virtualizer.measureElement : noopRef,
+    scrollToIndex,
+    scrollToOffset,
+    virtualizer
+  };
+}
+function noopRef() {
+}
+
+// src/virtual-list/use-virtual-log.ts
+var import_react3 = require("react");
+
+// src/terminal-output/log-helpers.ts
+var escapeRegExp = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+function queryMatcher(query) {
+  const q = query.trim();
+  return q ? new RegExp(escapeRegExp(q), "giu") : null;
+}
+function filterLines(lines, query) {
+  const matcher = queryMatcher(query);
+  const indexes = [];
+  lines.forEach((line, i) => {
+    if (!matcher) indexes.push(i);
+    else {
+      matcher.lastIndex = 0;
+      if (matcher.test(line)) indexes.push(i);
+    }
+  });
+  return indexes;
+}
+var FAILURE_PATTERNS = [
+  { tool: "tsc", kind: "error", pattern: /\berror TS\d+/ },
+  { tool: "pnpm", kind: "error", pattern: /\bERR_PNPM_[A-Z_]+/ },
+  { tool: "npm", kind: "error", pattern: /\bnpm (?:ERR!|error\b)/ },
+  { tool: "nx", kind: "failed tasks", pattern: /targets failed, including|Failed tasks/ },
+  { tool: "nx", kind: "task failed", pattern: /^\s*✖\s+nx run / },
+  { tool: "nx", kind: "failed", pattern: /^\s*✖\s+\d+\/\d+ failed/ },
+  { tool: "vitest", kind: "fail", pattern: /^\s*FAIL\s/ },
+  { tool: "vitest", kind: "test", pattern: /^\s*[×✗]\s/ },
+  { tool: "docker", kind: "error", pattern: /^\s*(?:Error response from daemon|ERROR: failed to solve|failed to solve|pull access denied)/ },
+  { tool: "docker", kind: "exit", pattern: /^\s*Container \S+\s+(?:Error|exited with code [1-9]\d*)/ },
+  { tool: "generic", kind: "error", pattern: /\b\w*Error\b(?: \[\w+\])?:/ }
+];
+var STACK_FRAME = /^\s*at\s/;
+function findFailures(lines, patterns = FAILURE_PATTERNS) {
+  const failures = [];
+  lines.forEach((line, index) => {
+    if (STACK_FRAME.test(line)) return;
+    const hit = patterns.find((p) => p.pattern.test(line));
+    if (hit) failures.push({ index, tool: hit.tool, kind: hit.kind });
+  });
+  return failures;
+}
+
+// src/terminal-output/use-follow-tail.ts
+var import_react2 = require("react");
+
+// src/terminal-output/follow-tail.ts
+var DEFAULT_TAIL_THRESHOLD = 24;
+function distanceFromEnd({ scrollTop, scrollHeight, clientHeight }) {
+  return scrollHeight - scrollTop - clientHeight;
+}
+function isNearEnd(metrics, threshold = DEFAULT_TAIL_THRESHOLD) {
+  return distanceFromEnd(metrics) <= threshold;
+}
+function shouldStick(prevAtBottom, metrics, userInitiated, threshold = DEFAULT_TAIL_THRESHOLD) {
+  if (!userInitiated) return prevAtBottom;
+  return isNearEnd(metrics, threshold);
+}
+function isUserScrollUp({ kind, delta = 0, lastTarget, scrollTop }, threshold = DEFAULT_TAIL_THRESHOLD) {
+  if (kind === "wheel") return delta < 0;
+  if (kind === "touch") return delta > 0;
+  if (kind === "gutter") return true;
+  return lastTarget !== null && scrollTop < lastTarget - threshold;
+}
+function unreadDelta(prevCount, nextCount, attached) {
+  if (attached) return 0;
+  return Math.max(0, nextCount - prevCount);
+}
+
+// src/terminal-output/use-follow-tail.ts
+var useIsomorphicLayoutEffect = typeof window === "undefined" ? import_react2.useEffect : import_react2.useLayoutEffect;
+function useFollowTail({
+  scrollRef,
+  itemCount,
+  scrollToEnd,
+  resetKey,
+  threshold = DEFAULT_TAIL_THRESHOLD
+}) {
+  const [atBottom, setAtBottom] = (0, import_react2.useState)(true);
+  const [unread, setUnread] = (0, import_react2.useState)(0);
+  const attached = (0, import_react2.useRef)(true);
+  const programmatic = (0, import_react2.useRef)(false);
+  const lastTarget = (0, import_react2.useRef)(null);
+  const lastTop = (0, import_react2.useRef)(0);
+  const frame = (0, import_react2.useRef)(0);
+  const prevCount = (0, import_react2.useRef)(itemCount);
+  const prevReset = (0, import_react2.useRef)(resetKey);
+  const latest = (0, import_react2.useRef)({ scrollToEnd, threshold });
+  latest.current = { scrollToEnd, threshold };
+  const attach = (0, import_react2.useCallback)((value) => {
+    attached.current = value;
+    setAtBottom(value);
+    if (value) setUnread(0);
+  }, []);
+  const followEnd = (0, import_react2.useCallback)(() => {
+    const el = scrollRef.current;
+    if (!el) return;
+    programmatic.current = true;
+    if (latest.current.scrollToEnd) latest.current.scrollToEnd();
+    else el.scrollTop = el.scrollHeight;
+    lastTarget.current = el.scrollHeight - el.clientHeight;
+    if (typeof requestAnimationFrame === "function") {
+      cancelAnimationFrame(frame.current);
+      frame.current = requestAnimationFrame(() => {
+        programmatic.current = false;
+      });
+    } else {
+      programmatic.current = false;
+    }
+  }, [scrollRef]);
+  useIsomorphicLayoutEffect(() => {
+    const count = prevCount.current;
+    prevCount.current = itemCount;
+    if (prevReset.current !== resetKey) {
+      prevReset.current = resetKey;
+      attach(true);
+      followEnd();
+      return;
+    }
+    if (attached.current) {
+      if (itemCount > 0) followEnd();
+      return;
+    }
+    const added = unreadDelta(count, itemCount, false);
+    if (added > 0) setUnread((n) => n + added);
+  }, [itemCount, resetKey, attach, followEnd]);
+  (0, import_react2.useEffect)(() => {
+    const el = scrollRef.current;
+    if (!el) return;
+    const takeOver = () => {
+      programmatic.current = false;
+      lastTarget.current = null;
+      if (attached.current) attach(false);
+    };
+    const onScroll = () => {
+      const { threshold: limit } = latest.current;
+      const movedUp = el.scrollTop < lastTop.current;
+      lastTop.current = el.scrollTop;
+      const info = { kind: "scroll", lastTarget: movedUp ? lastTarget.current : null, scrollTop: el.scrollTop };
+      const user = isUserScrollUp(info, limit);
+      if (user) takeOver();
+      const next = shouldStick(attached.current, el, user || !programmatic.current, limit);
+      if (next !== attached.current) attach(next);
+    };
+    const canScrollUp = () => el.scrollHeight > el.clientHeight && el.scrollTop > 0;
+    const onWheel = (e) => {
+      if (canScrollUp() && isUserScrollUp({ kind: "wheel", delta: e.deltaY, lastTarget: null, scrollTop: el.scrollTop })) takeOver();
+    };
+    let touchY = 0;
+    const onTouchStart = (e) => {
+      touchY = e.touches[0]?.clientY ?? 0;
+    };
+    const onTouchMove = (e) => {
+      const delta = (e.touches[0]?.clientY ?? touchY) - touchY;
+      if (canScrollUp() && isUserScrollUp({ kind: "touch", delta, lastTarget: null, scrollTop: el.scrollTop })) takeOver();
+    };
+    const onPointerDown = (e) => {
+      const gutter = el.offsetWidth - el.clientWidth;
+      if (e.target !== el || gutter <= 0) return;
+      if (e.clientX >= el.getBoundingClientRect().left + el.clientWidth) {
+        if (isUserScrollUp({ kind: "gutter", lastTarget: null, scrollTop: el.scrollTop })) takeOver();
+      }
+    };
+    el.addEventListener("scroll", onScroll, { passive: true });
+    el.addEventListener("wheel", onWheel, { passive: true });
+    el.addEventListener("touchstart", onTouchStart, { passive: true });
+    el.addEventListener("touchmove", onTouchMove, { passive: true });
+    el.addEventListener("pointerdown", onPointerDown, { passive: true });
+    return () => {
+      el.removeEventListener("scroll", onScroll);
+      el.removeEventListener("wheel", onWheel);
+      el.removeEventListener("touchstart", onTouchStart);
+      el.removeEventListener("touchmove", onTouchMove);
+      el.removeEventListener("pointerdown", onPointerDown);
+      if (typeof cancelAnimationFrame === "function") cancelAnimationFrame(frame.current);
+    };
+  }, [scrollRef, attach]);
+  const jumpToBottom = (0, import_react2.useCallback)(() => {
+    attach(true);
+    followEnd();
+  }, [attach, followEnd]);
+  return { atBottom, unread, jumpToBottom };
+}
+
+// src/virtual-list/log-index.ts
+function emptyScan() {
+  return { lineCount: 0, firstLine: void 0, failures: [] };
+}
+function scanFailures(prev, lines) {
+  const appendOnly = prev.lineCount > 0 && lines.length >= prev.lineCount && lines[0] === prev.firstLine;
+  const from = appendOnly ? prev.lineCount - 1 : 0;
+  const kept = appendOnly ? prev.failures.filter((f) => f.index < from) : [];
+  const fresh = findFailures(lines.slice(from)).map((f) => ({ ...f, index: f.index + from }));
+  return { lineCount: lines.length, firstLine: lines[0], failures: [...kept, ...fresh] };
+}
+function visiblePosition(visible, lineIndex) {
+  if (!visible) return lineIndex;
+  let lo = 0;
+  let hi = visible.length - 1;
+  while (lo <= hi) {
+    const mid = lo + hi >> 1;
+    const value = visible[mid];
+    if (value === lineIndex) return mid;
+    if (value < lineIndex) lo = mid + 1;
+    else hi = mid - 1;
+  }
+  return -1;
+}
+function stepIndex(current, count, direction) {
+  if (count === 0) return -1;
+  if (current < 0) return direction === 1 ? 0 : count - 1;
+  return (current + direction + count) % count;
+}
+
+// src/terminal-output/ansi.ts
+var ESCAPE_SOURCE = "\\x1b(?:\\[([0-?]*)([ -/]*)([@-~])|\\]([^\\x07\\x1b]*)(?:\\x07|\\x1b\\\\)|[ -/]+[0-~]|[0-~])";
+function stripAnsi(text) {
+  return text.replace(new RegExp(ESCAPE_SOURCE, "g"), "");
+}
+
+// src/virtual-list/log-text.ts
+function logToText(lines, options = {}) {
+  const rows = options.stripAnsi ? lines.map((line) => stripAnsi(line)) : lines;
+  return rows.join("\n");
+}
+function downloadText(filename, text) {
+  const url = URL.createObjectURL(new Blob([text], { type: "text/plain" }));
+  const a = document.createElement("a");
+  a.href = url;
+  a.download = filename;
+  a.click();
+  URL.revokeObjectURL(url);
+}
+
+// src/virtual-list/use-virtual-log.ts
+var DEFAULT_ROW = 18;
+function useVirtualLog({
+  lines,
+  scrollRef,
+  query = "",
+  estimateSize,
+  overscan = 12,
+  resetKey,
+  filename = "log.txt"
+}) {
+  const deferred = (0, import_react3.useDeferredValue)(query);
+  const isFiltering = deferred.trim() !== "";
+  const visible = (0, import_react3.useMemo)(() => isFiltering ? filterLines(lines, deferred) : null, [lines, deferred, isFiltering]);
+  const shownCount = visible ? visible.length : lines.length;
+  const scan = (0, import_react3.useRef)(emptyScan());
+  const failures = (0, import_react3.useMemo)(() => {
+    scan.current = scanFailures(scan.current, lines);
+    return scan.current.failures;
+  }, [lines]);
+  const list = useVirtualList({
+    count: shownCount,
+    estimateSize: estimateSize ?? (() => DEFAULT_ROW),
+    scrollRef,
+    overscan
+  });
+  const lastIndex = shownCount - 1;
+  const follow = useFollowTail({
+    scrollRef,
+    itemCount: lines.length,
+    scrollToEnd: () => {
+      if (!isFiltering) list.scrollToIndex(lastIndex, { align: "end" });
+    },
+    resetKey
+  });
+  const baseline = (0, import_react3.useRef)(shownCount);
+  (0, import_react3.useEffect)(() => {
+    baseline.current = shownCount;
+  }, [deferred, resetKey]);
+  const unread = isFiltering ? Math.max(0, shownCount - baseline.current) : follow.unread;
+  (0, import_react3.useEffect)(() => {
+    if (isFiltering) list.scrollToOffset(0);
+  }, [deferred]);
+  const [failurePosition, setFailurePosition] = (0, import_react3.useState)(-1);
+  const jumpToFailure = (0, import_react3.useCallback)(
+    (n) => {
+      const failure = failures[n];
+      if (!failure) return false;
+      const at = visiblePosition(visible, failure.index);
+      if (at < 0) return false;
+      setFailurePosition(n);
+      list.scrollToIndex(at, { align: "center" });
+      return true;
+    },
+    [failures, visible, list]
+  );
+  const step = (0, import_react3.useCallback)(
+    (direction) => {
+      for (let tries = 0, n = failurePosition; tries < failures.length; tries++) {
+        n = stepIndex(n, failures.length, direction);
+        if (jumpToFailure(n)) return true;
+      }
+      return false;
+    },
+    [failurePosition, failures.length, jumpToFailure]
+  );
+  const nextFailure = (0, import_react3.useCallback)(() => step(1), [step]);
+  const previousFailure = (0, import_react3.useCallback)(() => step(-1), [step]);
+  const text = (0, import_react3.useCallback)((options) => logToText(lines, options), [lines]);
+  const copyText = (0, import_react3.useCallback)(() => logToText(lines, { stripAnsi: true }), [lines]);
+  const download = (0, import_react3.useCallback)(
+    (name) => downloadText(name ?? filename, logToText(lines, { stripAnsi: true })),
+    [lines, filename]
+  );
+  const rows = list.items.map((item) => ({
+    ...item,
+    lineIndex: visible ? visible[item.index] ?? item.index : item.index
+  }));
+  return {
+    rows,
+    totalSize: list.totalSize,
+    measureRef: list.measureRef,
+    isFiltering,
+    shownCount,
+    atBottom: follow.atBottom,
+    unread,
+    jumpToBottom: follow.jumpToBottom,
+    failures,
+    failurePosition,
+    jumpToFailure,
+    nextFailure,
+    previousFailure,
+    text,
+    copyText,
+    download,
+    list
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  MAX_REALIGN_FRAMES,
+  downloadText,
+  initialVisibleCount,
+  logToText,
+  measuredOrEstimate,
+  shouldRealign,
+  targetOffset,
+  useVirtualList,
+  useVirtualLog
+});

package/dist/virtual-list.d.cts

@@ -0,0 +1,116 @@
+import { RefObject } from 'react';
+import { Virtualizer } from '@tanstack/react-virtual';
+import { a as Failure } from './log-helpers-rkbgYqZW.cjs';
+
+type ScrollAlign = 'start' | 'center' | 'end' | 'auto';
+declare const MAX_REALIGN_FRAMES = 3;
+/** A 0 height means "not laid out yet" (jsdom, or a read before first paint), so fall back to the estimate. */
+declare function measuredOrEstimate(measured: number | undefined, estimate: number): number;
+interface RealignInput {
+    align: ScrollAlign;
+    itemStart: number;
+    itemSize: number;
+    scrollOffset: number;
+    viewportSize: number;
+    frame: number;
+    maxFrames?: number;
+}
+declare function targetOffset(align: ScrollAlign, itemStart: number, itemSize: number, viewportSize: number): number;
+/** After rows above the target are measured the estimate can be off, so scroll again until the row sits where `align` says. */
+declare function shouldRealign({ align, itemStart, itemSize, scrollOffset, viewportSize, frame, maxFrames }: RealignInput): boolean;
+/** The first `initialCount` rows, used until the browser reports a viewport size. */
+declare function initialVisibleCount(count: number, initialCount: number): number;
+
+interface UseVirtualListOptions {
+    count: number;
+    estimateSize: (index: number) => number;
+    /** The overflow:auto element that scrolls. Omit with `windowScroll: true`. */
+    scrollRef?: RefObject<Element | null>;
+    /** Scroll with the page instead of an inner element. */
+    windowScroll?: boolean;
+    /** Distance from the top of the page to the list, for window scroll. */
+    scrollMargin?: number;
+    overscan?: number;
+    /** Measure each rendered row. Pass false when the app's own maths relies on `estimateSize`. */
+    measure?: boolean;
+    getItemKey?: (index: number) => string | number;
+    /** Rows rendered before the viewport size is known, so the server render isn't blank. */
+    initialCount?: number;
+}
+interface VirtualListItem {
+    index: number;
+    key: string | number | bigint;
+    start: number;
+    size: number;
+}
+interface ScrollToIndexOptions {
+    align?: ScrollAlign;
+}
+interface UseVirtualListResult {
+    items: VirtualListItem[];
+    totalSize: number;
+    /** Ref for each row element; the row also needs `data-index={item.index}`. */
+    measureRef: (el: Element | null) => void;
+    scrollToIndex: (index: number, options?: ScrollToIndexOptions) => void;
+    scrollToOffset: (offset: number) => void;
+    virtualizer: Virtualizer<Element, Element>;
+}
+declare function useVirtualList(options: UseVirtualListOptions): UseVirtualListResult;
+
+interface UseVirtualLogOptions {
+    /** Plain or raw lines; the last one may still be growing. */
+    lines: readonly string[];
+    scrollRef: RefObject<HTMLElement | null>;
+    /** Show only lines containing this text. Typing stays responsive on large logs. */
+    query?: string;
+    estimateSize?: (index: number) => number;
+    overscan?: number;
+    /** Snap back to the end whenever this changes (switching logs). */
+    resetKey?: unknown;
+    /** Filename used by `download`. */
+    filename?: string;
+}
+interface VirtualLogRow {
+    /** Position in the shown list. */
+    index: number;
+    /** Index into `lines`. */
+    lineIndex: number;
+    key: string | number | bigint;
+    start: number;
+    size: number;
+}
+interface UseVirtualLogResult {
+    rows: VirtualLogRow[];
+    totalSize: number;
+    measureRef: UseVirtualListResult['measureRef'];
+    isFiltering: boolean;
+    /** Lines shown: all of them, or the matches. */
+    shownCount: number;
+    atBottom: boolean;
+    unread: number;
+    jumpToBottom: () => void;
+    failures: readonly Failure[];
+    /** Which failure the last jump landed on, or -1. */
+    failurePosition: number;
+    jumpToFailure: (n: number) => boolean;
+    nextFailure: () => boolean;
+    previousFailure: () => boolean;
+    /** The whole log as text, whatever is rendered. */
+    text: (options?: {
+        stripAnsi?: boolean;
+    }) => string;
+    copyText: () => string;
+    download: (filename?: string) => void;
+    list: UseVirtualListResult;
+}
+declare function useVirtualLog({ lines, scrollRef, query, estimateSize, overscan, resetKey, filename, }: UseVirtualLogOptions): UseVirtualLogResult;
+
+interface LogToTextOptions {
+    /** Remove escape codes from each line. Default false: lines are joined as given. */
+    stripAnsi?: boolean;
+}
+declare function logToText(lines: readonly string[], options?: LogToTextOptions): string;
+/** Saves text as a file. The Blob URL is revoked right after the click. */
+declare function downloadText(filename: string, text: string): void;
+
+export { type LogToTextOptions, MAX_REALIGN_FRAMES, type RealignInput, type ScrollAlign, type ScrollToIndexOptions, type UseVirtualListOptions, type UseVirtualListResult, type UseVirtualLogOptions, type UseVirtualLogResult, type VirtualListItem, type VirtualLogRow, downloadText, initialVisibleCount, logToText, measuredOrEstimate, shouldRealign, targetOffset, useVirtualList, useVirtualLog };