@wow-two-beta/ui-vue 0.0.4 → 0.0.6

package/dist/foundation/virtualization/Windowing.d.ts

@@ -1,5 +1,5 @@
 /** The default number of off-screen items kept mounted on each side — enough to cover a fast flick's first frames. */
-export declare const DEFAULT_OVERSCAN = 3;
+export declare const DefaultOverscan = 3;
 /** Where a `scrollToIndex` should land the target item within the viewport. */
 export type ScrollAlignment = 
 /** Item's top edge at the viewport's top edge. */
@@ -25,12 +25,12 @@ export interface VirtualRange {
     readonly paddingEnd: number;
 }
 /** The empty-list range: renders nothing, reserves nothing. */
-export declare const EMPTY_RANGE: VirtualRange;
+export declare const EmptyRange: VirtualRange;
 /** Inputs to the windowing math. Supply `estimateSize` for a fixed list, `getOffset` for a variable one. */
 export interface ComputeRangeOptions {
     /** Current scroll position of the container along the list's axis, in pixels. Clamped into the scrollable range. */
     readonly scrollOffset: number;
-    /** Visible size of the container along the list's axis, in pixels (`clientHeight`, or `clientWidth` when horizontal). */
+    /** Visible size of the container along the list's axis, in pixels — `clientHeight`, or `clientWidth` horizontal. */
     readonly viewportSize: number;
     /** How many items the list has. Floored to a non-negative integer. */
     readonly itemCount: number;
@@ -40,7 +40,10 @@ export interface ComputeRangeOptions {
      * exactly what `useVirtualList` does. Omit entirely only alongside `getOffset`.
      */
     readonly estimateSize?: number | ((index: number) => number);
-    /** Extra items rendered beyond each edge of the viewport. Defaults to `0` here; `useVirtualList` defaults it to {@link DEFAULT_OVERSCAN}. */
+    /**
+     * Extra items rendered beyond each edge of the viewport. Defaults to `0`; `useVirtualList` overrides that
+     * with {@link DefaultOverscan}.
+     */
     readonly overscan?: number;
     /**
      * Cumulative start-offset accessor, defined for `0 .. itemCount` (where `itemCount` yields the total size).

package/dist/foundation/virtualization/index.d.ts

@@ -1,3 +1,3 @@
-export { buildMeasurements, findIndexAtOffset, findIndexByOffsetAccessor, itemOffset, itemSize, measurementsTotalSize, withMeasuredSize, EMPTY_MEASUREMENTS, type Measurements, } from './Measurements';
-export { computeRange, computeScrollOffset, DEFAULT_OVERSCAN, EMPTY_RANGE, type ComputeRangeOptions, type ComputeScrollOffsetOptions, type ScrollAlignment, type VirtualRange, } from './Windowing';
-export { useVirtualList, type UseVirtualListOptions, type VirtualItem, type VirtualList, } from './UseVirtualList';
+export { buildMeasurements, findIndexAtOffset, findIndexByOffsetAccessor, itemOffset, itemSize, measurementsTotalSize, withMeasuredSize, EmptyMeasurements, type Measurements, } from './Measurements';
+export { computeRange, computeScrollOffset, DefaultOverscan, EmptyRange, type ComputeRangeOptions, type ComputeScrollOffsetOptions, type ScrollAlignment, type VirtualRange, } from './Windowing';
+export { useVirtualList, type UseVirtualListOptions, type VirtualItem, type VirtualList } from './UseVirtualList';

package/dist/foundation/virtualization/index.js

@@ -1,12 +1,12 @@
 import { computed, toValue, shallowRef, watchPostEffect, watch } from "vue";
-import { u as useResizeObserver } from "../../chunks/useResizeObserver-BUU7lC-n.js";
+import { u as useResizeObserver } from "../../chunks/UseResizeObserver-BUU7lC-n.js";
 function normalizeSize(size) {
   return Number.isFinite(size) && size > 0 ? size : 0;
 }
-const EMPTY_MEASUREMENTS = { offsets: [0], count: 0 };
+const EmptyMeasurements = { offsets: [0], count: 0 };
 function buildMeasurements(count, sizeAt) {
   const safeCount = Number.isFinite(count) ? Math.max(0, Math.floor(count)) : 0;
-  if (safeCount === 0) return EMPTY_MEASUREMENTS;
+  if (safeCount === 0) return EmptyMeasurements;
   const offsets = new Array(safeCount + 1);
   offsets[0] = 0;
   let running = 0;
@@ -21,7 +21,7 @@ function itemOffset(measurements, index) {
   return measurements.offsets[clamped] ?? 0;
 }
 function itemSize(measurements, index) {
-  if (index < 0 || index >= measurements.count) return 0;
+  if (!Number.isInteger(index) || index < 0 || index >= measurements.count) return 0;
   return itemOffset(measurements, index + 1) - itemOffset(measurements, index);
 }
 function measurementsTotalSize(measurements) {
@@ -34,7 +34,7 @@ function findIndexByOffsetAccessor(offsetAt, count, offset) {
   let high = count - 1;
   let best = 0;
   while (low <= high) {
-    const mid = low + high >>> 1;
+    const mid = Math.floor(low + (high - low) / 2);
     if (offsetAt(mid) <= target) {
       best = mid;
       low = mid + 1;
@@ -45,14 +45,10 @@ function findIndexByOffsetAccessor(offsetAt, count, offset) {
   return best;
 }
 function findIndexAtOffset(measurements, offset) {
-  return findIndexByOffsetAccessor(
-    (index) => itemOffset(measurements, index),
-    measurements.count,
-    offset
-  );
+  return findIndexByOffsetAccessor((index) => itemOffset(measurements, index), measurements.count, offset);
 }
 function withMeasuredSize(measurements, index, size) {
-  if (index < 0 || index >= measurements.count) return measurements;
+  if (!Number.isInteger(index) || index < 0 || index >= measurements.count) return measurements;
   const next = normalizeSize(size);
   const delta = next - itemSize(measurements, index);
   if (delta === 0) return measurements;
@@ -62,8 +58,8 @@ function withMeasuredSize(measurements, index, size) {
   }
   return { offsets, count: measurements.count };
 }
-const DEFAULT_OVERSCAN = 3;
-const EMPTY_RANGE = {
+const DefaultOverscan = 3;
+const EmptyRange = {
   startIndex: 0,
   endIndex: -1,
   paddingStart: 0,
@@ -98,7 +94,7 @@ function resolveOffsetAt(options, itemCount) {
 }
 function computeRange(options) {
   const itemCount = Number.isFinite(options.itemCount) ? Math.max(0, Math.floor(options.itemCount)) : 0;
-  if (itemCount === 0) return EMPTY_RANGE;
+  if (itemCount === 0) return EmptyRange;
   const overscan = Math.max(0, Math.floor(finite(options.overscan ?? 0)));
   const viewportSize = Math.max(0, finite(options.viewportSize));
   const offsetAt = resolveOffsetAt(options, itemCount);
@@ -159,7 +155,7 @@ function computeScrollOffset(options) {
 function useVirtualList(options) {
   const horizontal = computed(() => toValue(options.horizontal) ?? false);
   const count = computed(() => toValue(options.count));
-  const overscan = computed(() => toValue(options.overscan) ?? DEFAULT_OVERSCAN);
+  const overscan = computed(() => toValue(options.overscan) ?? DefaultOverscan);
   const scrollOffset = shallowRef(0);
   const viewportSize = shallowRef(Math.max(0, options.initialViewportSize ?? 0));
   const measurementVersion = shallowRef(0);
@@ -244,7 +240,7 @@ function useVirtualList(options) {
   function measureItem(index, size) {
     if (!Number.isFinite(size) || size < 0) return;
     const current = measurements.value;
-    if (index < 0 || index >= current.count) return;
+    if (!Number.isInteger(index) || index < 0 || index >= current.count) return;
     const previous = itemSize(current, index);
     if (previous === size) return;
     measuredSizes.set(index, size);
@@ -283,9 +279,9 @@ function useVirtualList(options) {
   };
 }
 export {
-  DEFAULT_OVERSCAN,
-  EMPTY_MEASUREMENTS,
-  EMPTY_RANGE,
+  DefaultOverscan,
+  EmptyMeasurements,
+  EmptyRange,
   buildMeasurements,
   computeRange,
   computeScrollOffset,

package/dist/foundation/virtualization/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":["../../../src/foundation/virtualization/Measurements.ts","../../../src/foundation/virtualization/Windowing.ts","../../../src/foundation/virtualization/UseVirtualList.ts"],"sourcesContent":["// The item-geometry model the windowing math runs on: a prefix-sum array of cumulative start offsets, plus the\n// binary search that turns a scroll offset back into an item index.\n//\n// WHY A PREFIX SUM AND NOT AN ARRAY OF SIZES — this is the whole reason the file exists. A virtual list answers\n// exactly one question on every scroll frame: \"which item is at pixel X?\". Held as per-item sizes that question\n// is a running total, i.e. a linear scan: O(n) per frame, and at 100k rows it is precisely the cost\n// virtualization was introduced to remove. Held as CUMULATIVE offsets the array is sorted by construction, so\n// the same question is a binary search over it: O(log n) — ~17 comparisons at 100k items, and flat as the list\n// grows. Every read below is written against that invariant; nothing here may scan.\n//\n// LAYOUT: `offsets` has length `count + 1`. `offsets[i]` is item `i`'s start edge, and the extra tail entry\n// `offsets[count]` is the total size. That tail is not padding — it is what makes `size(i)` = `offsets[i + 1] -\n// offsets[i]` and `paddingEnd` = `total - offsets[endIndex + 1]` index-safe with no special case for the last\n// item, which is where off-by-one bugs in this kind of code normally live.\n//\n// IMMUTABILITY: every update returns a NEW `Measurements`, and returns the SAME object when nothing actually\n// changed. Consumers key work off that identity, and the no-op case is what stops a\n// measure -> render -> measure feedback loop from spinning.\n//\n// KNOWN COST: `withMeasuredSize` shifts every later offset, so recording one measured size is O(n). That is a\n// deliberate trade — measurements are rare (an item resizes) while searches are per-frame, so the cheap side is\n// the one that had to be O(log n). A Fenwick/BIT would make updates O(log n) too; it is the documented upgrade\n// path if a list ever re-measures thousands of rows per frame.\n\n/** A non-finite or negative size would break the array's monotonicity, so it is floored to 0 at the boundary. */\nfunction normalizeSize(size: number): number {\n  return Number.isFinite(size) && size > 0 ? size : 0;\n}\n\n/** Cumulative item geometry for a list of a known length. Treat as immutable — build a new one to change it. */\nexport interface Measurements {\n  /**\n   * Cumulative start offsets, length `count + 1` and non-decreasing. `offsets[i]` is item `i`'s start edge;\n   * `offsets[count]` is the list's total size.\n   */\n  readonly offsets: readonly number[];\n\n  /** The number of items described. Always a non-negative integer. */\n  readonly count: number;\n}\n\n/** The zero-item measurements — a shared, identity-stable empty value. */\nexport const EMPTY_MEASUREMENTS: Measurements = { offsets: [0], count: 0 };\n\n/**\n * Builds cumulative offsets by running `sizeAt` once per item. O(n), and the only O(n) pass in a steady-state\n * list: it runs on mount and when `count` changes, never per scroll frame.\n *\n * @param count How many items the list has. Non-integer or negative values are floored to a safe count.\n * @param sizeAt Size of the item at an index — a real measurement if one exists, otherwise an estimate.\n * @returns Measurements whose `offsets` are non-decreasing and whose tail entry is the total size.\n */\nexport function buildMeasurements(count: number, sizeAt: (index: number) => number): Measurements {\n  const safeCount = Number.isFinite(count) ? Math.max(0, Math.floor(count)) : 0;\n  if (safeCount === 0) return EMPTY_MEASUREMENTS;\n\n  const offsets = new Array<number>(safeCount + 1);\n  offsets[0] = 0;\n  let running = 0;\n  for (let index = 0; index < safeCount; index += 1) {\n    running += normalizeSize(sizeAt(index));\n    offsets[index + 1] = running;\n  }\n  return { offsets, count: safeCount };\n}\n\n/**\n * The start edge of the item at `index`. Reading `count` returns the total size (the tail entry); indices\n * outside `[0, count]` clamp rather than throw, so a stale index from a shrinking list degrades quietly.\n *\n * @param measurements The geometry to read.\n * @param index The item index, or `count` for the list's end edge.\n * @returns The cumulative offset in pixels.\n */\nexport function itemOffset(measurements: Measurements, index: number): number {\n  const clamped = Math.min(Math.max(Math.floor(index), 0), measurements.count);\n  // `offsets` always holds `count + 1` entries and `clamped` is inside that range, so the `?? 0` only exists to\n  // satisfy `noUncheckedIndexedAccess` — it cannot mask a real out-of-bounds read.\n  return measurements.offsets[clamped] ?? 0;\n}\n\n/**\n * The size of the item at `index`, derived from its own start edge and the next one.\n *\n * @param measurements The geometry to read.\n * @param index The item index.\n * @returns The item's size in pixels, or 0 when the index is out of range.\n */\nexport function itemSize(measurements: Measurements, index: number): number {\n  if (index < 0 || index >= measurements.count) return 0;\n  return itemOffset(measurements, index + 1) - itemOffset(measurements, index);\n}\n\n/**\n * The list's total size — the tail entry of the prefix sum.\n *\n * @param measurements The geometry to read.\n * @returns The summed size of every item in pixels.\n */\nexport function measurementsTotalSize(measurements: Measurements): number {\n  return itemOffset(measurements, measurements.count);\n}\n\n/**\n * Binary-searches a non-decreasing offset accessor for the last index whose start edge is at or before `offset`\n * — i.e. the item occupying that pixel. The accessor form (rather than an array) lets the fixed-size path search\n * a computed `index * itemSize` without materializing anything.\n *\n * Zero-size items share a start edge; the search resolves such a tie to the LAST of them, which keeps it\n * consistent with the fixed-size arithmetic path in `Windowing`.\n *\n * @param offsetAt Non-decreasing accessor returning the start edge of an index.\n * @param count How many items are searchable (indices `0 .. count - 1`).\n * @param offset The pixel offset to locate. Negative values are treated as 0.\n * @returns The item index at that offset, or `-1` when there are no items.\n */\nexport function findIndexByOffsetAccessor(\n  offsetAt: (index: number) => number,\n  count: number,\n  offset: number,\n): number {\n  if (count <= 0) return -1;\n  const target = Number.isFinite(offset) ? Math.max(0, offset) : 0;\n\n  let low = 0;\n  let high = count - 1;\n  // Item 0 starts at 0 and `target >= 0`, so index 0 always satisfies the predicate — the seed is never wrong.\n  let best = 0;\n  while (low <= high) {\n    const mid = (low + high) >>> 1;\n    if (offsetAt(mid) <= target) {\n      best = mid;\n      low = mid + 1;\n    } else {\n      high = mid - 1;\n    }\n  }\n  return best;\n}\n\n/**\n * Locates the item occupying `offset` in O(log n).\n *\n * @param measurements The geometry to search.\n * @param offset The pixel offset to locate. Negative values are treated as 0.\n * @returns The item index at that offset, or `-1` for an empty list.\n */\nexport function findIndexAtOffset(measurements: Measurements, offset: number): number {\n  return findIndexByOffsetAccessor(\n    (index) => itemOffset(measurements, index),\n    measurements.count,\n    offset,\n  );\n}\n\n/**\n * Records a real measured size for one item, shifting every later offset by the difference.\n *\n * Returns the SAME object when the size is unchanged or the index is out of range — consumers rely on that\n * identity to skip work, and it is what breaks the measure -> render -> measure cycle.\n *\n * @param measurements The geometry to update.\n * @param index The item that was measured.\n * @param size Its real size in pixels. Non-finite or negative values are floored to 0.\n * @returns New measurements, or the original when nothing changed.\n */\nexport function withMeasuredSize(\n  measurements: Measurements,\n  index: number,\n  size: number,\n): Measurements {\n  if (index < 0 || index >= measurements.count) return measurements;\n\n  const next = normalizeSize(size);\n  const delta = next - itemSize(measurements, index);\n  if (delta === 0) return measurements;\n\n  const offsets = measurements.offsets.slice();\n  for (let cursor = index + 1; cursor <= measurements.count; cursor += 1) {\n    offsets[cursor] = (offsets[cursor] ?? 0) + delta;\n  }\n  return { offsets, count: measurements.count };\n}\n","// The windowing math: given where the list is scrolled and how big the viewport is, which slice of items must\n// actually exist in the DOM, and how much empty space stands in for the rest.\n//\n// Everything here is a PURE FUNCTION of numbers — no Vue, no DOM, no time. That is deliberate: this is the\n// part with the off-by-one edges (boundary-exact scroll positions, overscan clamping, an empty list, a viewport\n// larger than the content), so it has to be exhaustively testable in node without a layout engine. The Vue\n// composable is a thin shell over these two functions.\n//\n// TWO PATHS, ONE ANSWER:\n//\n//  - FIXED SIZE (`estimateSize` is a number, no `getOffset`) — the index at a pixel is a division. O(1), no\n//    search, no array. The overwhelmingly common list.\n//  - VARIABLE SIZE (`getOffset` supplied) — the index at a pixel is a binary search over cumulative offsets,\n//    O(log n) (`Measurements.findIndexByOffsetAccessor`). A linear scan would be O(n) on EVERY scroll frame,\n//    which is the exact cost virtualization exists to remove, so it is not an option here.\n//\n// Both paths are defined to return the same thing: the last item whose start edge is at or before the pixel.\n// The tests assert they agree, because a silent divergence between them would only show up as a one-row flicker\n// at certain scroll positions.\n//\n// CLAMPING IS PART OF THE CONTRACT, not defensive noise. Real scroll containers report values this math must\n// survive: negative offsets during macOS rubber-band overscroll, offsets past the end during a bounce, a\n// viewport taller than the content, `count` dropping to 0 mid-flight. Each is clamped to the nearest sane\n// window rather than producing a NaN range that renders nothing.\n\nimport { findIndexByOffsetAccessor } from './Measurements';\n\n/** The default number of off-screen items kept mounted on each side — enough to cover a fast flick's first frames. */\nexport const DEFAULT_OVERSCAN = 3;\n\n/** Where a `scrollToIndex` should land the target item within the viewport. */\nexport type ScrollAlignment =\n  /** Item's top edge at the viewport's top edge. */\n  | 'start'\n  /** Item centred in the viewport. */\n  | 'center'\n  /** Item's bottom edge at the viewport's bottom edge. */\n  | 'end'\n  /** Scroll the shortest distance to bring the item fully into view; do nothing if it already is. */\n  | 'auto';\n\n/** The slice of a list that must be rendered, plus the empty space standing in for everything else. */\nexport interface VirtualRange {\n  /** First item index to render, overscan included. `0` when nothing renders. */\n  readonly startIndex: number;\n\n  /**\n   * Last item index to render, INCLUSIVE and overscan included. `-1` when nothing renders (an empty list), so\n   * `endIndex < startIndex` is the emptiness test and `endIndex - startIndex + 1` is always the rendered count.\n   */\n  readonly endIndex: number;\n\n  /** Pixels of skipped content before `startIndex` — the leading spacer's size. */\n  readonly paddingStart: number;\n\n  /** Pixels of skipped content after `endIndex` — the trailing spacer's size. */\n  readonly paddingEnd: number;\n}\n\n/** The empty-list range: renders nothing, reserves nothing. */\nexport const EMPTY_RANGE: VirtualRange = {\n  startIndex: 0,\n  endIndex: -1,\n  paddingStart: 0,\n  paddingEnd: 0,\n};\n\n/** Inputs to the windowing math. Supply `estimateSize` for a fixed list, `getOffset` for a variable one. */\nexport interface ComputeRangeOptions {\n  /** Current scroll position of the container along the list's axis, in pixels. Clamped into the scrollable range. */\n  readonly scrollOffset: number;\n\n  /** Visible size of the container along the list's axis, in pixels (`clientHeight`, or `clientWidth` when horizontal). */\n  readonly viewportSize: number;\n\n  /** How many items the list has. Floored to a non-negative integer. */\n  readonly itemCount: number;\n\n  /**\n   * Item sizing. A NUMBER selects the fixed-size fast path (O(1), no search). A FUNCTION is a per-index\n   * estimate and forces an O(n) prefix-sum build here, so pass `getOffset` instead on any hot path — that is\n   * exactly what `useVirtualList` does. Omit entirely only alongside `getOffset`.\n   */\n  readonly estimateSize?: number | ((index: number) => number);\n\n  /** Extra items rendered beyond each edge of the viewport. Defaults to `0` here; `useVirtualList` defaults it to {@link DEFAULT_OVERSCAN}. */\n  readonly overscan?: number;\n\n  /**\n   * Cumulative start-offset accessor, defined for `0 .. itemCount` (where `itemCount` yields the total size).\n   * Supplying it selects the variable-size path — the binary search. Takes precedence over `estimateSize`.\n   */\n  readonly getOffset?: (index: number) => number;\n}\n\n/** Inputs to {@link computeScrollOffset} — the same geometry, plus which item to reveal and how. */\nexport interface ComputeScrollOffsetOptions extends ComputeRangeOptions {\n  /** The item to bring into view. Clamped into `[0, itemCount - 1]`. */\n  readonly index: number;\n\n  /** Where the item should land. Defaults to `'auto'`. */\n  readonly align?: ScrollAlignment;\n}\n\n/** Replaces NaN/Infinity with 0 so one bad input can never poison the arithmetic downstream. */\nfunction finite(value: number): number {\n  return Number.isFinite(value) ? value : 0;\n}\n\n/** Constrains `value` to `[min, max]`. */\nfunction clamp(value: number, min: number, max: number): number {\n  return Math.min(Math.max(value, min), max);\n}\n\n/**\n * Resolves the options bag to a single non-decreasing offset accessor over `0 .. itemCount`, so the range math\n * below never has to branch on how the list is sized. The `estimateSize`-as-function case materializes a prefix\n * sum (O(n)) — see the `estimateSize` docs for why that path is a convenience, not a hot path.\n */\nfunction resolveOffsetAt(\n  options: ComputeRangeOptions,\n  itemCount: number,\n): (index: number) => number {\n  const { getOffset, estimateSize } = options;\n\n  if (getOffset) {\n    return (index) => finite(getOffset(clamp(Math.floor(index), 0, itemCount)));\n  }\n\n  if (typeof estimateSize === 'number') {\n    const size = Math.max(0, finite(estimateSize));\n    return (index) => clamp(Math.floor(index), 0, itemCount) * size;\n  }\n\n  if (typeof estimateSize === 'function') {\n    const offsets = new Array<number>(itemCount + 1);\n    offsets[0] = 0;\n    let running = 0;\n    for (let index = 0; index < itemCount; index += 1) {\n      running += Math.max(0, finite(estimateSize(index)));\n      offsets[index + 1] = running;\n    }\n    return (index) => offsets[clamp(Math.floor(index), 0, itemCount)] ?? 0;\n  }\n\n  // Neither sizing input given — every item is zero-sized. Degenerate but total, never NaN.\n  return () => 0;\n}\n\n/**\n * Computes the slice of items overlapping the viewport, widened by `overscan` and clamped to the list.\n *\n * Boundary rule: an item whose start edge sits EXACTLY on the viewport's bottom edge is not visible and is not\n * included (before overscan). Both sizing paths implement that identically.\n *\n * @param options Scroll position, viewport size, item count, and the sizing input.\n * @returns The indices to render plus the leading/trailing spacer sizes. `paddingStart` + the rendered items'\n * combined size + `paddingEnd` always equals the list's total size.\n */\nexport function computeRange(options: ComputeRangeOptions): VirtualRange {\n  const itemCount = Number.isFinite(options.itemCount)\n    ? Math.max(0, Math.floor(options.itemCount))\n    : 0;\n  if (itemCount === 0) return EMPTY_RANGE;\n\n  const overscan = Math.max(0, Math.floor(finite(options.overscan ?? 0)));\n  const viewportSize = Math.max(0, finite(options.viewportSize));\n\n  const offsetAt = resolveOffsetAt(options, itemCount);\n  const totalSize = offsetAt(itemCount);\n\n  // The container cannot scroll past its own content; a bounce or a stale offset lands on the last window\n  // rather than on an empty one. This also collapses the \"viewport bigger than content\" case to offset 0.\n  const maxScroll = Math.max(0, totalSize - viewportSize);\n  const scrollOffset = clamp(finite(options.scrollOffset), 0, maxScroll);\n  const bottomEdge = scrollOffset + viewportSize;\n\n  // The fixed path is arithmetic only when the uniform size is positive; a zero/degenerate size falls through\n  // to the search so both paths still agree on the answer.\n  const uniformSize =\n    !options.getOffset && typeof options.estimateSize === 'number'\n      ? Math.max(0, finite(options.estimateSize))\n      : 0;\n\n  let firstVisible: number;\n  let lastVisible: number;\n\n  if (uniformSize > 0) {\n    firstVisible = clamp(Math.floor(scrollOffset / uniformSize), 0, itemCount - 1);\n    // `ceil(edge / size) - 1` is the last item STARTING before the bottom edge, which is the boundary rule.\n    lastVisible = clamp(Math.ceil(bottomEdge / uniformSize) - 1, 0, itemCount - 1);\n    if (lastVisible < firstVisible) lastVisible = firstVisible;\n  } else {\n    firstVisible = findIndexByOffsetAccessor(offsetAt, itemCount, scrollOffset);\n    lastVisible = findIndexByOffsetAccessor(offsetAt, itemCount, bottomEdge);\n    // The search is inclusive of `<= bottomEdge`; an item starting exactly ON the edge is off-screen. Only\n    // step back when doing so still leaves something rendered.\n    if (lastVisible > firstVisible && offsetAt(lastVisible) >= bottomEdge) lastVisible -= 1;\n  }\n\n  const startIndex = Math.max(0, firstVisible - overscan);\n  const endIndex = Math.min(itemCount - 1, lastVisible + overscan);\n\n  return {\n    startIndex,\n    endIndex,\n    paddingStart: Math.max(0, offsetAt(startIndex)),\n    paddingEnd: Math.max(0, totalSize - offsetAt(endIndex + 1)),\n  };\n}\n\n/** The target offset for a given alignment, before clamping into the scrollable range. */\nfunction alignedOffset(\n  align: ScrollAlignment,\n  start: number,\n  end: number,\n  viewportSize: number,\n  current: number,\n): number {\n  switch (align) {\n    case 'start':\n      return start;\n    case 'end':\n      return end - viewportSize;\n    case 'center':\n      return start + (end - start) / 2 - viewportSize / 2;\n    case 'auto': {\n      // Already fully visible, or already covering the whole viewport (an item taller than it) — hold still.\n      // Moving here would be the jump `auto` exists to avoid.\n      if (start >= current && end <= current + viewportSize) return current;\n      if (start <= current && end >= current + viewportSize) return current;\n      // An item that cannot fit pins its top edge; otherwise take the shorter of the two edges.\n      if (end - start >= viewportSize) return start;\n      return start < current ? start : end - viewportSize;\n    }\n  }\n}\n\n/**\n * Computes the scroll offset that brings `index` into view under a given alignment.\n *\n * `'auto'` is a no-op when the item is already fully visible (or already spans the whole viewport), which is\n * what makes it safe to call on every selection change without fighting the user's scrolling.\n *\n * @param options Geometry plus the target `index` and `align`.\n * @returns The offset to assign to the container, clamped to `[0, totalSize - viewportSize]`.\n */\nexport function computeScrollOffset(options: ComputeScrollOffsetOptions): number {\n  const itemCount = Number.isFinite(options.itemCount)\n    ? Math.max(0, Math.floor(options.itemCount))\n    : 0;\n  if (itemCount === 0) return 0;\n\n  const viewportSize = Math.max(0, finite(options.viewportSize));\n  const offsetAt = resolveOffsetAt(options, itemCount);\n  const totalSize = offsetAt(itemCount);\n\n  const maxScroll = Math.max(0, totalSize - viewportSize);\n  const current = clamp(finite(options.scrollOffset), 0, maxScroll);\n\n  const index = clamp(Math.floor(finite(options.index)), 0, itemCount - 1);\n  const start = offsetAt(index);\n  const end = offsetAt(index + 1);\n\n  return clamp(alignedOffset(options.align ?? 'auto', start, end, viewportSize, current), 0, maxScroll);\n}\n","// The Vue binding for the windowing math: watch a scroll container, and hand back only the items that need to\n// exist in the DOM. Headless — it renders nothing and dictates no markup; it returns numbers.\n//\n// WHAT THE COMPOSABLE ACTUALLY OWNS: three pieces of state (scroll offset, viewport size, a measurement\n// version) and the watchers that keep them true. Everything geometric is delegated to\n// `Windowing`/`Measurements`, which stay pure and node-testable. If a change is about \"which items\", it\n// belongs there, not here.\n//\n// THE CONTAINER IS RESOLVED REACTIVELY, which deletes the original's re-resolve-on-every-commit effect. A\n// template ref is itself reactive, so a swapped, unmounted, or conditionally rendered container simply\n// re-triggers the computed. `getScrollElement` is still supported for a container held outside a ref, but it\n// is only re-read when something else in the same computed changes — prefer `target` when the node can move.\n//\n// SCROLL ANCHORING — the hard part, and the reason this composable is more than 40 lines:\n//\n//   When an item ABOVE the fold turns out to be taller than its estimate, every pixel below it shifts down by\n//   the difference. The user is looking at those pixels, so the list visibly jumps under them — the classic\n//   \"content leaps while you're reading\" bug in every hand-rolled virtual list. The fix is to add the same\n//   delta to the scroll position, which cancels the shift exactly: same content, same pixels.\n//\n//   Two details make it actually work:\n//\n//   1. WHEN to compensate. Only when the re-measured item ends AT OR ABOVE the viewport's top edge. If it\n//      merely straddles that edge, its own top is pinned above the fold and does not move, so the content the\n//      user is reading is already stable — compensating there would CAUSE the jump instead of preventing it.\n//      Below the fold, nothing visible moves at all.\n//\n//   2. WHEN to apply it. Not inside `measureItem`: at that moment the container is still its old height, so\n//      assigning a larger `scrollTop` gets silently clamped by the browser and the correction is lost. It is\n//      staged as an accumulated delta and applied from a `flush: 'post'` WATCHER — after Vue patches the taller\n//      spacer, before the browser paints. The applied value is then read back from the DOM, because the browser\n//      is the authority on how far the container can actually scroll.\n//\n//   Deltas accumulate rather than overwrite: several items commonly re-measure in one flush, and each must\n//   contribute.\n//\n// LOOP SAFETY: `measureItem` is a no-op when the size is unchanged. That single guard is what keeps a consumer\n// wiring it to a ResizeObserver from spinning measure -> render -> measure forever.\n//\n// SSR: every DOM read sits behind a resolved-element guard inside a post-flush watcher, and `target` resolves\n// to `null` on the server, so nothing here touches `scrollTop`, `clientHeight`, or `ResizeObserver` during a\n// server render. The reported window is the one implied by `initialViewportSize`.\n\nimport {\n  computed,\n  shallowRef,\n  toValue,\n  watch,\n  watchPostEffect,\n  type ComputedRef,\n  type MaybeRefOrGetter,\n  type ShallowRef,\n} from 'vue';\n\nimport { useResizeObserver } from '../hooks';\n\nimport {\n  buildMeasurements,\n  itemOffset,\n  itemSize,\n  measurementsTotalSize,\n  type Measurements,\n} from './Measurements';\nimport {\n  DEFAULT_OVERSCAN,\n  computeRange,\n  computeScrollOffset,\n  type ScrollAlignment,\n  type VirtualRange,\n} from './Windowing';\n\n/** One rendered row: where to put it and how big it is. */\nexport interface VirtualItem {\n  /** Index into the consumer's data array. */\n  readonly index: number;\n\n  /** Offset of the item's start edge from the list's start, in pixels — the value to position it at. */\n  readonly start: number;\n\n  /** The item's current size in pixels: its real measurement if one was recorded, otherwise the estimate. */\n  readonly size: number;\n\n  /** Stable key for `v-for` — `getItemKey(index)` when supplied, otherwise the index itself. */\n  readonly key: string | number;\n}\n\n/** Configures a `useVirtualList` binding. */\nexport interface UseVirtualListOptions {\n  /** How many items the full list has. */\n  readonly count: MaybeRefOrGetter<number>;\n\n  /**\n   * Estimated size of the item at an index, in pixels, used until a real measurement arrives. Read at build\n   * time — a CHANGED estimator only takes effect when `count` changes or an item is re-measured.\n   */\n  readonly estimateSize: (index: number) => number;\n\n  /** The scrolling container, as a ref or getter. A `useTemplateRef` drops straight in. */\n  readonly target?: MaybeRefOrGetter<HTMLElement | null | undefined>;\n\n  /** Callback form of the same thing, for containers not held in a ref. Takes precedence over `target`. */\n  readonly getScrollElement?: () => HTMLElement | null;\n\n  /** Extra items rendered beyond each edge of the viewport. Defaults to {@link DEFAULT_OVERSCAN}. */\n  readonly overscan?: MaybeRefOrGetter<number | undefined>;\n\n  /** Whether the list scrolls horizontally (`scrollLeft`/`clientWidth`) instead of vertically. Defaults to `false`. */\n  readonly horizontal?: MaybeRefOrGetter<boolean | undefined>;\n\n  /** Viewport size assumed before the container is measured — set it to render a sensible first frame under SSR. Defaults to `0`. */\n  readonly initialViewportSize?: number;\n\n  /** Stable key for an item, for reordering data. Defaults to the index. */\n  readonly getItemKey?: (index: number) => string | number;\n}\n\n/** What a virtualized list hands back to its consumer. */\nexport interface VirtualList {\n  /** The items to render right now, in index order, overscan included. Empty when the list is empty. */\n  readonly virtualItems: ComputedRef<readonly VirtualItem[]>;\n\n  /** Combined size of every item — the size the scrollable spacer must have for the scrollbar to be honest. */\n  readonly totalSize: ComputedRef<number>;\n\n  /** The underlying window: rendered index bounds plus leading/trailing spacer sizes, for padding-based layouts. */\n  readonly range: ComputedRef<VirtualRange>;\n\n  /** Pixels of content skipped before the first rendered item. Same as `range.paddingStart`. */\n  readonly paddingStart: ComputedRef<number>;\n\n  /** Pixels of content skipped after the last rendered item. Same as `range.paddingEnd`. */\n  readonly paddingEnd: ComputedRef<number>;\n\n  /** The container's current scroll position along the list's axis, as the composable last observed it. */\n  readonly scrollOffset: Readonly<ShallowRef<number>>;\n\n  /** The container's measured viewport size along the list's axis. `0` until the container mounts. */\n  readonly viewportSize: Readonly<ShallowRef<number>>;\n\n  /**\n   * Scrolls the container so item `index` is in view.\n   *\n   * @param index Item to reveal; clamped into range.\n   * @param align Where it should land. Defaults to `'auto'` — a no-op when the item is already fully visible.\n   */\n  scrollToIndex(index: number, align?: ScrollAlignment): void;\n\n  /**\n   * Records an item's real measured size, replacing its estimate. A no-op when the size is unchanged, so it is\n   * safe to call from a ResizeObserver or a post-flush watcher on every update.\n   *\n   * Preserves the visible content when the item sits above the fold — see this file's header.\n   *\n   * @param index The item that was measured.\n   * @param size Its real size in pixels.\n   */\n  measureItem(index: number, size: number): void;\n}\n\n/**\n * Virtualizes a list: subscribes to a scroll container and reports only the items overlapping its viewport.\n *\n * Headless by design — it produces geometry, never markup. The consumer renders a spacer sized `totalSize` and\n * positions each `virtualItem` at its `start`. See the `foundation/virtualization` barrel for a usage sketch.\n *\n * @param options The item count, size estimator, and the container to watch.\n * @returns The current window, total size, and the `scrollToIndex` / `measureItem` controls.\n */\nexport function useVirtualList(options: UseVirtualListOptions): VirtualList {\n  const horizontal = computed(() => toValue(options.horizontal) ?? false);\n  const count = computed(() => toValue(options.count));\n  const overscan = computed(() => toValue(options.overscan) ?? DEFAULT_OVERSCAN);\n\n  const scrollOffset = shallowRef(0);\n  const viewportSize = shallowRef(Math.max(0, options.initialViewportSize ?? 0));\n  const measurementVersion = shallowRef(0);\n\n  const scrollElement = computed<HTMLElement | null>(\n    () => options.getScrollElement?.() ?? toValue(options.target) ?? null,\n  );\n\n  /** Real sizes reported through `measureItem`, keyed by index; absent entries fall back to the estimate. */\n  const measuredSizes = new Map<number, number>();\n\n  /** Scroll correction owed to items that grew/shrank above the fold, applied after the next patch. */\n  let pendingScrollDelta = 0;\n\n  const measurements = computed<Measurements>(() => {\n    // `measurementVersion` is the content key for the measured-size map, which is a plain `Map` and therefore\n    // cannot be tracked itself. `estimateSize` is read at build time on purpose: making it reactive would\n    // rebuild every offset whenever an inline arrow was re-created.\n    void measurementVersion.value;\n    return buildMeasurements(count.value, (index) => {\n      const measured = measuredSizes.get(index);\n      return measured ?? options.estimateSize(index);\n    });\n  });\n\n  const totalSize = computed(() => measurementsTotalSize(measurements.value));\n\n  // Track the container's scroll position. `passive` because this listener never calls `preventDefault`, so the\n  // browser may keep scrolling on its own thread. Post-flush and element-guarded, so nothing runs on the server.\n  watchPostEffect((onCleanup) => {\n    const element = scrollElement.value;\n    if (!element) return;\n    const isHorizontal = horizontal.value;\n\n    const sync = (): void => {\n      const next = isHorizontal ? element.scrollLeft : element.scrollTop;\n      if (scrollOffset.value !== next) scrollOffset.value = next;\n    };\n\n    // Adopt the position the container already has — a restored scroll or a deep link would otherwise render\n    // the top of the list until the user's first scroll.\n    sync();\n    element.addEventListener('scroll', sync, { passive: true });\n    onCleanup(() => element.removeEventListener('scroll', sync));\n  });\n\n  function readViewportSize(): void {\n    const element = scrollElement.value;\n    if (!element) return;\n    // `clientHeight`/`clientWidth`, not the observer's `contentRect`: the scrollable viewport includes padding\n    // and excludes the scrollbar, which is exactly what these report and `contentRect` does not.\n    const next = horizontal.value ? element.clientWidth : element.clientHeight;\n    if (viewportSize.value !== next) viewportSize.value = next;\n  }\n\n  useResizeObserver(scrollElement, readViewportSize, () => scrollElement.value !== null);\n\n  // Seed the size before the first paint. The observer also fires on attach, but that lands a frame later — long\n  // enough to paint one frame of an unwindowed (or empty) list.\n  watchPostEffect(readViewportSize);\n\n  // Apply the anchoring correction owed from the last `measureItem` batch. Runs AFTER the patch that resized\n  // the spacer, so the container can actually reach the new offset, and BEFORE paint, so nothing jumps.\n  // Non-immediate: there is nothing to correct on the first pass, and the server has no container.\n  watch(\n    [measurementVersion, horizontal],\n    () => {\n      const delta = pendingScrollDelta;\n      if (delta === 0) return;\n      pendingScrollDelta = 0;\n\n      const element = scrollElement.value;\n      if (!element) return;\n\n      const isHorizontal = horizontal.value;\n      const currentPosition = isHorizontal ? element.scrollLeft : element.scrollTop;\n      const next = Math.max(0, currentPosition + delta);\n      if (isHorizontal) element.scrollLeft = next;\n      else element.scrollTop = next;\n\n      // Read back rather than trusting the arithmetic — the browser clamps to the container's real scroll range.\n      const applied = isHorizontal ? element.scrollLeft : element.scrollTop;\n      if (scrollOffset.value !== applied) scrollOffset.value = applied;\n    },\n    { flush: 'post' },\n  );\n\n  const range = computed<VirtualRange>(() =>\n    computeRange({\n      scrollOffset: scrollOffset.value,\n      viewportSize: viewportSize.value,\n      itemCount: count.value,\n      overscan: overscan.value,\n      // Always the variable-size path: measured sizes can make any list non-uniform at any time, and the\n      // binary search over the prefix sum is O(log n) either way.\n      getOffset: (index) => itemOffset(measurements.value, index),\n    }),\n  );\n\n  const virtualItems = computed<readonly VirtualItem[]>(() => {\n    const window = range.value;\n    if (window.endIndex < window.startIndex) return [];\n\n    const { getItemKey } = options;\n    const current = measurements.value;\n    const items: VirtualItem[] = [];\n    for (let index = window.startIndex; index <= window.endIndex; index += 1) {\n      items.push({\n        index,\n        start: itemOffset(current, index),\n        size: itemSize(current, index),\n        key: getItemKey ? getItemKey(index) : index,\n      });\n    }\n    return items;\n  });\n\n  function measureItem(index: number, size: number): void {\n    if (!Number.isFinite(size) || size < 0) return;\n\n    const current = measurements.value;\n    if (index < 0 || index >= current.count) return;\n\n    const previous = itemSize(current, index);\n    // The guard that stops a measure -> render -> measure loop dead. Everything below re-derives.\n    if (previous === size) return;\n\n    measuredSizes.set(index, size);\n\n    // Compensate only for an item entirely above the viewport's top edge — see this file's header for why a\n    // straddling item must NOT be compensated. Accumulate: a whole batch of items can re-measure in one flush.\n    const endsAboveFold = itemOffset(current, index) + previous <= scrollOffset.value;\n    if (endsAboveFold) pendingScrollDelta += size - previous;\n\n    measurementVersion.value += 1;\n  }\n\n  function scrollToIndex(index: number, align: ScrollAlignment = 'auto'): void {\n    const element = scrollElement.value;\n    if (!element) return;\n\n    const isHorizontal = horizontal.value;\n    const current = measurements.value;\n    // Read position and size live off the DOM: `scrollToIndex` is often called right after a mutation, before\n    // the composable's state has caught up, and the stale value would land the item in the wrong place.\n    const next = computeScrollOffset({\n      index,\n      align,\n      scrollOffset: isHorizontal ? element.scrollLeft : element.scrollTop,\n      viewportSize: isHorizontal ? element.clientWidth : element.clientHeight,\n      itemCount: current.count,\n      getOffset: (target) => itemOffset(current, target),\n    });\n\n    if (isHorizontal) element.scrollLeft = next;\n    else element.scrollTop = next;\n\n    const applied = isHorizontal ? element.scrollLeft : element.scrollTop;\n    if (scrollOffset.value !== applied) scrollOffset.value = applied;\n  }\n\n  return {\n    virtualItems,\n    totalSize,\n    range,\n    paddingStart: computed(() => range.value.paddingStart),\n    paddingEnd: computed(() => range.value.paddingEnd),\n    scrollOffset,\n    viewportSize,\n    scrollToIndex,\n    measureItem,\n  };\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sources":["../../../src/foundation/virtualization/Measurements.ts","../../../src/foundation/virtualization/Windowing.ts","../../../src/foundation/virtualization/UseVirtualList.ts"],"sourcesContent":["// The item-geometry model the windowing math runs on: a prefix-sum array of cumulative start offsets, plus the\n// binary search that turns a scroll offset back into an item index.\n//\n// WHY A PREFIX SUM AND NOT AN ARRAY OF SIZES — this is the whole reason the file exists. A virtual list answers\n// exactly one question on every scroll frame: \"which item is at pixel X?\". Held as per-item sizes that question\n// is a running total, i.e. a linear scan: O(n) per frame, and at 100k rows it is precisely the cost\n// virtualization was introduced to remove. Held as CUMULATIVE offsets the array is sorted by construction, so\n// the same question is a binary search over it: O(log n) — ~17 comparisons at 100k items, and flat as the list\n// grows. Every read below is written against that invariant; nothing here may scan.\n//\n// LAYOUT: `offsets` has length `count + 1`. `offsets[i]` is item `i`'s start edge, and the extra tail entry\n// `offsets[count]` is the total size. That tail is not padding — it is what makes `size(i)` = `offsets[i + 1] -\n// offsets[i]` and `paddingEnd` = `total - offsets[endIndex + 1]` index-safe with no special case for the last\n// item, which is where off-by-one bugs in this kind of code normally live.\n//\n// IMMUTABILITY: every update returns a NEW `Measurements`, and returns the SAME object when nothing actually\n// changed. Consumers key work off that identity, and the no-op case is what stops a\n// measure -> render -> measure feedback loop from spinning.\n//\n// KNOWN COST: `withMeasuredSize` shifts every later offset, so recording one measured size is O(n). That is a\n// deliberate trade — measurements are rare (an item resizes) while searches are per-frame, so the cheap side is\n// the one that had to be O(log n). A Fenwick/BIT would make updates O(log n) too; it is the documented upgrade\n// path if a list ever re-measures thousands of rows per frame.\n\n/** A non-finite or negative size would break the array's monotonicity, so it is floored to 0 at the boundary. */\nfunction normalizeSize(size: number): number {\n  return Number.isFinite(size) && size > 0 ? size : 0;\n}\n\n/** Cumulative item geometry for a list of a known length. Treat as immutable — build a new one to change it. */\nexport interface Measurements {\n  /**\n   * Cumulative start offsets, length `count + 1` and non-decreasing. `offsets[i]` is item `i`'s start edge;\n   * `offsets[count]` is the list's total size.\n   */\n  readonly offsets: ReadonlyArray<number>;\n\n  /** The number of items described. Always a non-negative integer. */\n  readonly count: number;\n}\n\n/** The zero-item measurements — a shared, identity-stable empty value. */\nexport const EmptyMeasurements: Measurements = { offsets: [0], count: 0 };\n\n/**\n * Builds cumulative offsets by running `sizeAt` once per item. O(n), and the only O(n) pass in a steady-state\n * list: it runs on mount and when `count` changes, never per scroll frame.\n *\n * @param count How many items the list has. Non-integer or negative values are floored to a safe count.\n * @param sizeAt Size of the item at an index — a real measurement if one exists, otherwise an estimate.\n * @returns Measurements whose `offsets` are non-decreasing and whose tail entry is the total size.\n */\nexport function buildMeasurements(count: number, sizeAt: (index: number) => number): Measurements {\n  const safeCount = Number.isFinite(count) ? Math.max(0, Math.floor(count)) : 0;\n  if (safeCount === 0) return EmptyMeasurements;\n\n  const offsets = new Array<number>(safeCount + 1);\n  offsets[0] = 0;\n  let running = 0;\n  for (let index = 0; index < safeCount; index += 1) {\n    running += normalizeSize(sizeAt(index));\n    offsets[index + 1] = running;\n  }\n  return { offsets, count: safeCount };\n}\n\n/**\n * The start edge of the item at `index`. Reading `count` returns the total size (the tail entry); indices\n * outside `[0, count]` clamp rather than throw, so a stale index from a shrinking list degrades quietly.\n *\n * @param measurements The geometry to read.\n * @param index The item index, or `count` for the list's end edge.\n * @returns The cumulative offset in pixels.\n */\nexport function itemOffset(measurements: Measurements, index: number): number {\n  const clamped = Math.min(Math.max(Math.floor(index), 0), measurements.count);\n  // `offsets` always holds `count + 1` entries and `clamped` is inside that range, so the `?? 0` only exists to\n  // satisfy `noUncheckedIndexedAccess` — it cannot mask a real out-of-bounds read.\n  return measurements.offsets[clamped] ?? 0;\n}\n\n/**\n * The size of the item at `index`, derived from its own start edge and the next one.\n *\n * @param measurements The geometry to read.\n * @param index The item index.\n * @returns The item's size in pixels, or 0 when the index is out of range.\n */\nexport function itemSize(measurements: Measurements, index: number): number {\n  if (!Number.isInteger(index) || index < 0 || index >= measurements.count) return 0;\n  return itemOffset(measurements, index + 1) - itemOffset(measurements, index);\n}\n\n/**\n * The list's total size — the tail entry of the prefix sum.\n *\n * @param measurements The geometry to read.\n * @returns The summed size of every item in pixels.\n */\nexport function measurementsTotalSize(measurements: Measurements): number {\n  return itemOffset(measurements, measurements.count);\n}\n\n/**\n * Binary-searches a non-decreasing offset accessor for the last index whose start edge is at or before `offset`\n * — i.e. the item occupying that pixel. The accessor form (rather than an array) lets the fixed-size path search\n * a computed `index * itemSize` without materializing anything.\n *\n * Zero-size items share a start edge; the search resolves such a tie to the LAST of them, which keeps it\n * consistent with the fixed-size arithmetic path in `Windowing`.\n *\n * @param offsetAt Non-decreasing accessor returning the start edge of an index.\n * @param count How many items are searchable (indices `0 .. count - 1`).\n * @param offset The pixel offset to locate. Negative values are treated as 0.\n * @returns The item index at that offset, or `-1` when there are no items.\n */\nexport function findIndexByOffsetAccessor(offsetAt: (index: number) => number, count: number, offset: number): number {\n  if (count <= 0) return -1;\n  const target = Number.isFinite(offset) ? Math.max(0, offset) : 0;\n\n  let low = 0;\n  let high = count - 1;\n  // Item 0 starts at 0 and `target >= 0`, so index 0 always satisfies the predicate — the seed is never wrong.\n  let best = 0;\n  while (low <= high) {\n    const mid = Math.floor(low + (high - low) / 2);\n    if (offsetAt(mid) <= target) {\n      best = mid;\n      low = mid + 1;\n    } else {\n      high = mid - 1;\n    }\n  }\n  return best;\n}\n\n/**\n * Locates the item occupying `offset` in O(log n).\n *\n * @param measurements The geometry to search.\n * @param offset The pixel offset to locate. Negative values are treated as 0.\n * @returns The item index at that offset, or `-1` for an empty list.\n */\nexport function findIndexAtOffset(measurements: Measurements, offset: number): number {\n  return findIndexByOffsetAccessor((index) => itemOffset(measurements, index), measurements.count, offset);\n}\n\n/**\n * Records a real measured size for one item, shifting every later offset by the difference.\n *\n * Returns the SAME object when the size is unchanged or the index is out of range — consumers rely on that\n * identity to skip work, and it is what breaks the measure -> render -> measure cycle.\n *\n * @param measurements The geometry to update.\n * @param index The item that was measured.\n * @param size Its real size in pixels. Non-finite or negative values are floored to 0.\n * @returns New measurements, or the original when nothing changed.\n */\nexport function withMeasuredSize(measurements: Measurements, index: number, size: number): Measurements {\n  if (!Number.isInteger(index) || index < 0 || index >= measurements.count) return measurements;\n\n  const next = normalizeSize(size);\n  const delta = next - itemSize(measurements, index);\n  if (delta === 0) return measurements;\n\n  const offsets = measurements.offsets.slice();\n  for (let cursor = index + 1; cursor <= measurements.count; cursor += 1) {\n    offsets[cursor] = (offsets[cursor] ?? 0) + delta;\n  }\n  return { offsets, count: measurements.count };\n}\n","// The windowing math: given where the list is scrolled and how big the viewport is, which slice of items must\n// actually exist in the DOM, and how much empty space stands in for the rest.\n//\n// Everything here is a PURE FUNCTION of numbers — no Vue, no DOM, no time. That is deliberate: this is the\n// part with the off-by-one edges (boundary-exact scroll positions, overscan clamping, an empty list, a viewport\n// larger than the content), so it has to be exhaustively testable in node without a layout engine. The Vue\n// composable is a thin shell over these two functions.\n//\n// TWO PATHS, ONE ANSWER:\n//\n//  - FIXED SIZE (`estimateSize` is a number, no `getOffset`) — the index at a pixel is a division. O(1), no\n//    search, no array. The overwhelmingly common list.\n//  - VARIABLE SIZE (`getOffset` supplied) — the index at a pixel is a binary search over cumulative offsets,\n//    O(log n) (`Measurements.findIndexByOffsetAccessor`). A linear scan would be O(n) on EVERY scroll frame,\n//    which is the exact cost virtualization exists to remove, so it is not an option here.\n//\n// Both paths are defined to return the same thing: the last item whose start edge is at or before the pixel.\n// The tests assert they agree, because a silent divergence between them would only show up as a one-row flicker\n// at certain scroll positions.\n//\n// CLAMPING IS PART OF THE CONTRACT, not defensive noise. Real scroll containers report values this math must\n// survive: negative offsets during macOS rubber-band overscroll, offsets past the end during a bounce, a\n// viewport taller than the content, `count` dropping to 0 mid-flight. Each is clamped to the nearest sane\n// window rather than producing a NaN range that renders nothing.\n\nimport { findIndexByOffsetAccessor } from './Measurements';\n\n/** The default number of off-screen items kept mounted on each side — enough to cover a fast flick's first frames. */\nexport const DefaultOverscan = 3;\n\n/** Where a `scrollToIndex` should land the target item within the viewport. */\nexport type ScrollAlignment =\n  /** Item's top edge at the viewport's top edge. */\n  | 'start'\n  /** Item centred in the viewport. */\n  | 'center'\n  /** Item's bottom edge at the viewport's bottom edge. */\n  | 'end'\n  /** Scroll the shortest distance to bring the item fully into view; do nothing if it already is. */\n  | 'auto';\n\n/** The slice of a list that must be rendered, plus the empty space standing in for everything else. */\nexport interface VirtualRange {\n  /** First item index to render, overscan included. `0` when nothing renders. */\n  readonly startIndex: number;\n\n  /**\n   * Last item index to render, INCLUSIVE and overscan included. `-1` when nothing renders (an empty list), so\n   * `endIndex < startIndex` is the emptiness test and `endIndex - startIndex + 1` is always the rendered count.\n   */\n  readonly endIndex: number;\n\n  /** Pixels of skipped content before `startIndex` — the leading spacer's size. */\n  readonly paddingStart: number;\n\n  /** Pixels of skipped content after `endIndex` — the trailing spacer's size. */\n  readonly paddingEnd: number;\n}\n\n/** The empty-list range: renders nothing, reserves nothing. */\nexport const EmptyRange: VirtualRange = {\n  startIndex: 0,\n  endIndex: -1,\n  paddingStart: 0,\n  paddingEnd: 0,\n};\n\n/** Inputs to the windowing math. Supply `estimateSize` for a fixed list, `getOffset` for a variable one. */\nexport interface ComputeRangeOptions {\n  /** Current scroll position of the container along the list's axis, in pixels. Clamped into the scrollable range. */\n  readonly scrollOffset: number;\n\n  /** Visible size of the container along the list's axis, in pixels — `clientHeight`, or `clientWidth` horizontal. */\n  readonly viewportSize: number;\n\n  /** How many items the list has. Floored to a non-negative integer. */\n  readonly itemCount: number;\n\n  /**\n   * Item sizing. A NUMBER selects the fixed-size fast path (O(1), no search). A FUNCTION is a per-index\n   * estimate and forces an O(n) prefix-sum build here, so pass `getOffset` instead on any hot path — that is\n   * exactly what `useVirtualList` does. Omit entirely only alongside `getOffset`.\n   */\n  readonly estimateSize?: number | ((index: number) => number);\n\n  /**\n   * Extra items rendered beyond each edge of the viewport. Defaults to `0`; `useVirtualList` overrides that\n   * with {@link DefaultOverscan}.\n   */\n  readonly overscan?: number;\n\n  /**\n   * Cumulative start-offset accessor, defined for `0 .. itemCount` (where `itemCount` yields the total size).\n   * Supplying it selects the variable-size path — the binary search. Takes precedence over `estimateSize`.\n   */\n  readonly getOffset?: (index: number) => number;\n}\n\n/** Inputs to {@link computeScrollOffset} — the same geometry, plus which item to reveal and how. */\nexport interface ComputeScrollOffsetOptions extends ComputeRangeOptions {\n  /** The item to bring into view. Clamped into `[0, itemCount - 1]`. */\n  readonly index: number;\n\n  /** Where the item should land. Defaults to `'auto'`. */\n  readonly align?: ScrollAlignment;\n}\n\n/** Replaces NaN/Infinity with 0 so one bad input can never poison the arithmetic downstream. */\nfunction finite(value: number): number {\n  return Number.isFinite(value) ? value : 0;\n}\n\n/** Constrains `value` to `[min, max]`. */\nfunction clamp(value: number, min: number, max: number): number {\n  return Math.min(Math.max(value, min), max);\n}\n\n/**\n * Resolves the options bag to a single non-decreasing offset accessor over `0 .. itemCount`, so the range math\n * below never has to branch on how the list is sized. The `estimateSize`-as-function case materializes a prefix\n * sum (O(n)) — see the `estimateSize` docs for why that path is a convenience, not a hot path.\n */\nfunction resolveOffsetAt(options: ComputeRangeOptions, itemCount: number): (index: number) => number {\n  const { getOffset, estimateSize } = options;\n\n  if (getOffset) {\n    return (index) => finite(getOffset(clamp(Math.floor(index), 0, itemCount)));\n  }\n\n  if (typeof estimateSize === 'number') {\n    const size = Math.max(0, finite(estimateSize));\n    return (index) => clamp(Math.floor(index), 0, itemCount) * size;\n  }\n\n  if (typeof estimateSize === 'function') {\n    const offsets = new Array<number>(itemCount + 1);\n    offsets[0] = 0;\n    let running = 0;\n    for (let index = 0; index < itemCount; index += 1) {\n      running += Math.max(0, finite(estimateSize(index)));\n      offsets[index + 1] = running;\n    }\n    return (index) => offsets[clamp(Math.floor(index), 0, itemCount)] ?? 0;\n  }\n\n  // Neither sizing input given — every item is zero-sized. Degenerate but total, never NaN.\n  return () => 0;\n}\n\n/**\n * Computes the slice of items overlapping the viewport, widened by `overscan` and clamped to the list.\n *\n * Boundary rule: an item whose start edge sits EXACTLY on the viewport's bottom edge is not visible and is not\n * included (before overscan). Both sizing paths implement that identically.\n *\n * @param options Scroll position, viewport size, item count, and the sizing input.\n * @returns The indices to render plus the leading/trailing spacer sizes. `paddingStart` + the rendered items'\n * combined size + `paddingEnd` always equals the list's total size.\n */\nexport function computeRange(options: ComputeRangeOptions): VirtualRange {\n  const itemCount = Number.isFinite(options.itemCount) ? Math.max(0, Math.floor(options.itemCount)) : 0;\n  if (itemCount === 0) return EmptyRange;\n\n  const overscan = Math.max(0, Math.floor(finite(options.overscan ?? 0)));\n  const viewportSize = Math.max(0, finite(options.viewportSize));\n\n  const offsetAt = resolveOffsetAt(options, itemCount);\n  const totalSize = offsetAt(itemCount);\n\n  // The container cannot scroll past its own content; a bounce or a stale offset lands on the last window\n  // rather than on an empty one. This also collapses the \"viewport bigger than content\" case to offset 0.\n  const maxScroll = Math.max(0, totalSize - viewportSize);\n  const scrollOffset = clamp(finite(options.scrollOffset), 0, maxScroll);\n  const bottomEdge = scrollOffset + viewportSize;\n\n  // The fixed path is arithmetic only when the uniform size is positive; a zero/degenerate size falls through\n  // to the search so both paths still agree on the answer.\n  const uniformSize =\n    !options.getOffset && typeof options.estimateSize === 'number' ? Math.max(0, finite(options.estimateSize)) : 0;\n\n  let firstVisible: number;\n  let lastVisible: number;\n\n  if (uniformSize > 0) {\n    firstVisible = clamp(Math.floor(scrollOffset / uniformSize), 0, itemCount - 1);\n    // `ceil(edge / size) - 1` is the last item STARTING before the bottom edge, which is the boundary rule.\n    lastVisible = clamp(Math.ceil(bottomEdge / uniformSize) - 1, 0, itemCount - 1);\n    if (lastVisible < firstVisible) lastVisible = firstVisible;\n  } else {\n    firstVisible = findIndexByOffsetAccessor(offsetAt, itemCount, scrollOffset);\n    lastVisible = findIndexByOffsetAccessor(offsetAt, itemCount, bottomEdge);\n    // The search is inclusive of `<= bottomEdge`; an item starting exactly ON the edge is off-screen. Only\n    // step back when doing so still leaves something rendered.\n    if (lastVisible > firstVisible && offsetAt(lastVisible) >= bottomEdge) lastVisible -= 1;\n  }\n\n  const startIndex = Math.max(0, firstVisible - overscan);\n  const endIndex = Math.min(itemCount - 1, lastVisible + overscan);\n\n  return {\n    startIndex,\n    endIndex,\n    paddingStart: Math.max(0, offsetAt(startIndex)),\n    paddingEnd: Math.max(0, totalSize - offsetAt(endIndex + 1)),\n  };\n}\n\n/** The target offset for a given alignment, before clamping into the scrollable range. */\nfunction alignedOffset(\n  align: ScrollAlignment,\n  start: number,\n  end: number,\n  viewportSize: number,\n  current: number,\n): number {\n  switch (align) {\n    case 'start':\n      return start;\n    case 'end':\n      return end - viewportSize;\n    case 'center':\n      return start + (end - start) / 2 - viewportSize / 2;\n    case 'auto': {\n      // Already fully visible, or already covering the whole viewport (an item taller than it) — hold still.\n      // Moving here would be the jump `auto` exists to avoid.\n      if (start >= current && end <= current + viewportSize) return current;\n      if (start <= current && end >= current + viewportSize) return current;\n      // An item that cannot fit pins its top edge; otherwise take the shorter of the two edges.\n      if (end - start >= viewportSize) return start;\n      return start < current ? start : end - viewportSize;\n    }\n  }\n}\n\n/**\n * Computes the scroll offset that brings `index` into view under a given alignment.\n *\n * `'auto'` is a no-op when the item is already fully visible (or already spans the whole viewport), which is\n * what makes it safe to call on every selection change without fighting the user's scrolling.\n *\n * @param options Geometry plus the target `index` and `align`.\n * @returns The offset to assign to the container, clamped to `[0, totalSize - viewportSize]`.\n */\nexport function computeScrollOffset(options: ComputeScrollOffsetOptions): number {\n  const itemCount = Number.isFinite(options.itemCount) ? Math.max(0, Math.floor(options.itemCount)) : 0;\n  if (itemCount === 0) return 0;\n\n  const viewportSize = Math.max(0, finite(options.viewportSize));\n  const offsetAt = resolveOffsetAt(options, itemCount);\n  const totalSize = offsetAt(itemCount);\n\n  const maxScroll = Math.max(0, totalSize - viewportSize);\n  const current = clamp(finite(options.scrollOffset), 0, maxScroll);\n\n  const index = clamp(Math.floor(finite(options.index)), 0, itemCount - 1);\n  const start = offsetAt(index);\n  const end = offsetAt(index + 1);\n\n  return clamp(alignedOffset(options.align ?? 'auto', start, end, viewportSize, current), 0, maxScroll);\n}\n","// The Vue binding for the windowing math: watch a scroll container, and hand back only the items that need to\n// exist in the DOM. Headless — it renders nothing and dictates no markup; it returns numbers.\n//\n// WHAT THE COMPOSABLE ACTUALLY OWNS: three pieces of state (scroll offset, viewport size, a measurement\n// version) and the watchers that keep them true. Everything geometric is delegated to\n// `Windowing`/`Measurements`, which stay pure and node-testable. If a change is about \"which items\", it\n// belongs there, not here.\n//\n// THE CONTAINER IS RESOLVED REACTIVELY, which deletes the original's re-resolve-on-every-commit effect. A\n// template ref is itself reactive, so a swapped, unmounted, or conditionally rendered container simply\n// re-triggers the computed. `getScrollElement` is still supported for a container held outside a ref, but it\n// is only re-read when something else in the same computed changes — prefer `target` when the node can move.\n//\n// SCROLL ANCHORING — the hard part, and the reason this composable is more than 40 lines:\n//\n//   When an item ABOVE the fold turns out to be taller than its estimate, every pixel below it shifts down by\n//   the difference. The user is looking at those pixels, so the list visibly jumps under them — the classic\n//   \"content leaps while you're reading\" bug in every hand-rolled virtual list. The fix is to add the same\n//   delta to the scroll position, which cancels the shift exactly: same content, same pixels.\n//\n//   Two details make it actually work:\n//\n//   1. WHEN to compensate. Only when the re-measured item ends AT OR ABOVE the viewport's top edge. If it\n//      merely straddles that edge, its own top is pinned above the fold and does not move, so the content the\n//      user is reading is already stable — compensating there would CAUSE the jump instead of preventing it.\n//      Below the fold, nothing visible moves at all.\n//\n//   2. WHEN to apply it. Not inside `measureItem`: at that moment the container is still its old height, so\n//      assigning a larger `scrollTop` gets silently clamped by the browser and the correction is lost. It is\n//      staged as an accumulated delta and applied from a `flush: 'post'` WATCHER — after Vue patches the taller\n//      spacer, before the browser paints. The applied value is then read back from the DOM, because the browser\n//      is the authority on how far the container can actually scroll.\n//\n//   Deltas accumulate rather than overwrite: several items commonly re-measure in one flush, and each must\n//   contribute.\n//\n// LOOP SAFETY: `measureItem` is a no-op when the size is unchanged. That single guard is what keeps a consumer\n// wiring it to a ResizeObserver from spinning measure -> render -> measure forever.\n//\n// SSR: every DOM read sits behind a resolved-element guard inside a post-flush watcher, and `target` resolves\n// to `null` on the server, so nothing here touches `scrollTop`, `clientHeight`, or `ResizeObserver` during a\n// server render. The reported window is the one implied by `initialViewportSize`.\n\nimport {\n  computed,\n  shallowRef,\n  toValue,\n  watch,\n  watchPostEffect,\n  type ComputedRef,\n  type MaybeRefOrGetter,\n  type ShallowRef,\n} from 'vue';\n\nimport { useResizeObserver } from '../observers';\n\nimport { buildMeasurements, itemOffset, itemSize, measurementsTotalSize, type Measurements } from './Measurements';\nimport {\n  DefaultOverscan,\n  computeRange,\n  computeScrollOffset,\n  type ScrollAlignment,\n  type VirtualRange,\n} from './Windowing';\n\n/** One rendered row: where to put it and how big it is. */\nexport interface VirtualItem {\n  /** Index into the consumer's data array. */\n  readonly index: number;\n\n  /** Offset of the item's start edge from the list's start, in pixels — the value to position it at. */\n  readonly start: number;\n\n  /** The item's current size in pixels: its real measurement if one was recorded, otherwise the estimate. */\n  readonly size: number;\n\n  /** Stable key for `v-for` — `getItemKey(index)` when supplied, otherwise the index itself. */\n  readonly key: string | number;\n}\n\n/** Configures a `useVirtualList` binding. */\nexport interface UseVirtualListOptions {\n  /** How many items the full list has. */\n  readonly count: MaybeRefOrGetter<number>;\n\n  /**\n   * Estimated size of the item at an index, in pixels, used until a real measurement arrives. Read at build\n   * time — a CHANGED estimator only takes effect when `count` changes or an item is re-measured.\n   */\n  readonly estimateSize: (index: number) => number;\n\n  /** The scrolling container, as a ref or getter. A `useTemplateRef` drops straight in. */\n  readonly target?: MaybeRefOrGetter<HTMLElement | null | undefined>;\n\n  /** Callback form of the same thing, for containers not held in a ref. Takes precedence over `target`. */\n  readonly getScrollElement?: () => HTMLElement | null;\n\n  /** Extra items rendered beyond each edge of the viewport. Defaults to {@link DefaultOverscan}. */\n  readonly overscan?: MaybeRefOrGetter<number | undefined>;\n\n  /** Whether the list scrolls horizontally (`scrollLeft`/`clientWidth`) instead of vertically. Defaults to `false`. */\n  readonly horizontal?: MaybeRefOrGetter<boolean | undefined>;\n\n  /**\n   * Viewport size assumed before the container is measured — set it to render a sensible first frame under SSR.\n   * Defaults to `0`.\n   */\n  readonly initialViewportSize?: number;\n\n  /** Stable key for an item, for reordering data. Defaults to the index. */\n  readonly getItemKey?: (index: number) => string | number;\n}\n\n/** What a virtualized list hands back to its consumer. */\nexport interface VirtualList {\n  /** The items to render right now, in index order, overscan included. Empty when the list is empty. */\n  readonly virtualItems: ComputedRef<ReadonlyArray<VirtualItem>>;\n\n  /** Combined size of every item — the size the scrollable spacer must have for the scrollbar to be honest. */\n  readonly totalSize: ComputedRef<number>;\n\n  /** The underlying window: rendered index bounds plus leading/trailing spacer sizes, for padding-based layouts. */\n  readonly range: ComputedRef<VirtualRange>;\n\n  /** Pixels of content skipped before the first rendered item. Same as `range.paddingStart`. */\n  readonly paddingStart: ComputedRef<number>;\n\n  /** Pixels of content skipped after the last rendered item. Same as `range.paddingEnd`. */\n  readonly paddingEnd: ComputedRef<number>;\n\n  /** The container's current scroll position along the list's axis, as the composable last observed it. */\n  readonly scrollOffset: Readonly<ShallowRef<number>>;\n\n  /** The container's measured viewport size along the list's axis. `0` until the container mounts. */\n  readonly viewportSize: Readonly<ShallowRef<number>>;\n\n  /**\n   * Scrolls the container so item `index` is in view.\n   *\n   * @param index Item to reveal; clamped into range.\n   * @param align Where it should land. Defaults to `'auto'` — a no-op when the item is already fully visible.\n   */\n  scrollToIndex(index: number, align?: ScrollAlignment): void;\n\n  /**\n   * Records an item's real measured size, replacing its estimate. A no-op when the size is unchanged, so it is\n   * safe to call from a ResizeObserver or a post-flush watcher on every update.\n   *\n   * Preserves the visible content when the item sits above the fold — see this file's header.\n   *\n   * @param index The item that was measured.\n   * @param size Its real size in pixels.\n   */\n  measureItem(index: number, size: number): void;\n}\n\n/**\n * Virtualizes a list: subscribes to a scroll container and reports only the items overlapping its viewport.\n *\n * Headless by design — it produces geometry, never markup. The consumer renders a spacer sized `totalSize` and\n * positions each `virtualItem` at its `start`. See the `foundation/virtualization` barrel for a usage sketch.\n *\n * @param options The item count, size estimator, and the container to watch.\n * @returns The current window, total size, and the `scrollToIndex` / `measureItem` controls.\n */\nexport function useVirtualList(options: UseVirtualListOptions): VirtualList {\n  const horizontal = computed(() => toValue(options.horizontal) ?? false);\n  const count = computed(() => toValue(options.count));\n  const overscan = computed(() => toValue(options.overscan) ?? DefaultOverscan);\n\n  const scrollOffset = shallowRef(0);\n  const viewportSize = shallowRef(Math.max(0, options.initialViewportSize ?? 0));\n  const measurementVersion = shallowRef(0);\n\n  const scrollElement = computed<HTMLElement | null>(\n    () => options.getScrollElement?.() ?? toValue(options.target) ?? null,\n  );\n\n  /** Real sizes reported through `measureItem`, keyed by index; absent entries fall back to the estimate. */\n  const measuredSizes = new Map<number, number>();\n\n  /** Scroll correction owed to items that grew/shrank above the fold, applied after the next patch. */\n  let pendingScrollDelta = 0;\n\n  const measurements = computed<Measurements>(() => {\n    // `measurementVersion` is the content key for the measured-size map, which is a plain `Map` and therefore\n    // cannot be tracked itself. `estimateSize` is read at build time on purpose: making it reactive would\n    // rebuild every offset whenever an inline arrow was re-created.\n    void measurementVersion.value;\n    return buildMeasurements(count.value, (index) => {\n      const measured = measuredSizes.get(index);\n      return measured ?? options.estimateSize(index);\n    });\n  });\n\n  const totalSize = computed(() => measurementsTotalSize(measurements.value));\n\n  // Track the container's scroll position. `passive` because this listener never calls `preventDefault`, so the\n  // browser may keep scrolling on its own thread. Post-flush and element-guarded, so nothing runs on the server.\n  watchPostEffect((onCleanup) => {\n    const element = scrollElement.value;\n    if (!element) return;\n    const isHorizontal = horizontal.value;\n\n    const sync = (): void => {\n      const next = isHorizontal ? element.scrollLeft : element.scrollTop;\n      if (scrollOffset.value !== next) scrollOffset.value = next;\n    };\n\n    // Adopt the position the container already has — a restored scroll or a deep link would otherwise render\n    // the top of the list until the user's first scroll.\n    sync();\n    element.addEventListener('scroll', sync, { passive: true });\n    onCleanup(() => element.removeEventListener('scroll', sync));\n  });\n\n  function readViewportSize(): void {\n    const element = scrollElement.value;\n    if (!element) return;\n    // `clientHeight`/`clientWidth`, not the observer's `contentRect`: the scrollable viewport includes padding\n    // and excludes the scrollbar, which is exactly what these report and `contentRect` does not.\n    const next = horizontal.value ? element.clientWidth : element.clientHeight;\n    if (viewportSize.value !== next) viewportSize.value = next;\n  }\n\n  useResizeObserver(scrollElement, readViewportSize, () => scrollElement.value !== null);\n\n  // Seed the size before the first paint. The observer also fires on attach, but that lands a frame later — long\n  // enough to paint one frame of an unwindowed (or empty) list.\n  watchPostEffect(readViewportSize);\n\n  // Apply the anchoring correction owed from the last `measureItem` batch. Runs AFTER the patch that resized\n  // the spacer, so the container can actually reach the new offset, and BEFORE paint, so nothing jumps.\n  // Non-immediate: there is nothing to correct on the first pass, and the server has no container.\n  watch(\n    [measurementVersion, horizontal],\n    () => {\n      const delta = pendingScrollDelta;\n      if (delta === 0) return;\n      pendingScrollDelta = 0;\n\n      const element = scrollElement.value;\n      if (!element) return;\n\n      const isHorizontal = horizontal.value;\n      const currentPosition = isHorizontal ? element.scrollLeft : element.scrollTop;\n      const next = Math.max(0, currentPosition + delta);\n      if (isHorizontal) element.scrollLeft = next;\n      else element.scrollTop = next;\n\n      // Read back rather than trusting the arithmetic — the browser clamps to the container's real scroll range.\n      const applied = isHorizontal ? element.scrollLeft : element.scrollTop;\n      if (scrollOffset.value !== applied) scrollOffset.value = applied;\n    },\n    { flush: 'post' },\n  );\n\n  const range = computed<VirtualRange>(() =>\n    computeRange({\n      scrollOffset: scrollOffset.value,\n      viewportSize: viewportSize.value,\n      itemCount: count.value,\n      overscan: overscan.value,\n      // Always the variable-size path: measured sizes can make any list non-uniform at any time, and the\n      // binary search over the prefix sum is O(log n) either way.\n      getOffset: (index) => itemOffset(measurements.value, index),\n    }),\n  );\n\n  const virtualItems = computed<readonly VirtualItem[]>(() => {\n    const window = range.value;\n    if (window.endIndex < window.startIndex) return [];\n\n    const { getItemKey } = options;\n    const current = measurements.value;\n    const items: VirtualItem[] = [];\n    for (let index = window.startIndex; index <= window.endIndex; index += 1) {\n      items.push({\n        index,\n        start: itemOffset(current, index),\n        size: itemSize(current, index),\n        key: getItemKey ? getItemKey(index) : index,\n      });\n    }\n    return items;\n  });\n\n  function measureItem(index: number, size: number): void {\n    if (!Number.isFinite(size) || size < 0) return;\n\n    const current = measurements.value;\n    if (!Number.isInteger(index) || index < 0 || index >= current.count) return;\n\n    const previous = itemSize(current, index);\n    // The guard that stops a measure -> render -> measure loop dead. Everything below re-derives.\n    if (previous === size) return;\n\n    measuredSizes.set(index, size);\n\n    // Compensate only for an item entirely above the viewport's top edge — see this file's header for why a\n    // straddling item must NOT be compensated. Accumulate: a whole batch of items can re-measure in one flush.\n    const endsAboveFold = itemOffset(current, index) + previous <= scrollOffset.value;\n    if (endsAboveFold) pendingScrollDelta += size - previous;\n\n    measurementVersion.value += 1;\n  }\n\n  function scrollToIndex(index: number, align: ScrollAlignment = 'auto'): void {\n    const element = scrollElement.value;\n    if (!element) return;\n\n    const isHorizontal = horizontal.value;\n    const current = measurements.value;\n    // Read position and size live off the DOM: `scrollToIndex` is often called right after a mutation, before\n    // the composable's state has caught up, and the stale value would land the item in the wrong place.\n    const next = computeScrollOffset({\n      index,\n      align,\n      scrollOffset: isHorizontal ? element.scrollLeft : element.scrollTop,\n      viewportSize: isHorizontal ? element.clientWidth : element.clientHeight,\n      itemCount: current.count,\n      getOffset: (target) => itemOffset(current, target),\n    });\n\n    if (isHorizontal) element.scrollLeft = next;\n    else element.scrollTop = next;\n\n    const applied = isHorizontal ? element.scrollLeft : element.scrollTop;\n    if (scrollOffset.value !== applied) scrollOffset.value = applied;\n  }\n\n  return {\n    virtualItems,\n    totalSize,\n    range,\n    paddingStart: computed(() => range.value.paddingStart),\n    paddingEnd: computed(() => range.value.paddingEnd),\n    scrollOffset,\n    viewportSize,\n    scrollToIndex,\n    measureItem,\n  };\n}\n"],"names":[],"mappings":"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"}

package/dist/foundation/workers/RunInWorker.d.ts

@@ -1,34 +1,22 @@
-/** The outcome of a {@link runInWorker} attempt. */
-export type RunInWorkerResult<TValue> = {
-    /** The function ran on the worker thread and returned. */
-    readonly status: 'ok';
-    /** The value it returned, structured-cloned back. */
-    readonly value: TValue;
-} | {
-    /** No `Worker`, `Blob`, or `URL.createObjectURL` here — SSR, or a CSP blocking `blob:` workers. Nothing ran. */
-    readonly status: 'unsupported';
-} | {
-    /** The function threw, the worker failed to start, or the deadline elapsed. */
-    readonly status: 'failed';
-    /** The normalized failure — the worker's own error where one crossed the boundary. */
-    readonly error: Error;
-};
+import { WorkerRunResult } from './models/WorkerRunResult';
+export type { WorkerRunFailure } from './models/WorkerRunFailure';
+export type { WorkerRunResult } from './models/WorkerRunResult';
 /** Tunes a {@link runInWorker} call. */
 export interface RunInWorkerOptions {
-    /** The deadline in milliseconds. On lapse the worker is terminated and the result is `failed` with a `TimeoutError`. Omit for none. */
+    /** Deadline (ms), omit for none. On lapse the worker is terminated and the result is `failed` (`TimeoutError`). */
     readonly timeoutMs?: number;
     /**
      * The objects to transfer into the worker instead of cloning. Each is NEUTERED in the caller: an
      * `ArrayBuffer` passed here has `byteLength === 0` once the call returns.
      */
-    readonly transfer?: readonly Transferable[];
+    readonly transfer?: ReadonlyArray<Transferable>;
 }
 /**
  * Runs `fn` on a throwaway worker thread and resolves with its result.
  *
  * ```ts
  * const result = await runInWorker((rows: number[]) => rows.reduce((a, b) => a + b, 0), [bigArray]);
- * if (result.status === 'ok') console.log(result.value);
+ * if (result.ok) console.log(result.value);
  * ```
  *
  * `fn` MUST be self-contained — it is stringified, so it captures nothing from the scope it was written
@@ -36,6 +24,6 @@ export interface RunInWorkerOptions {
  * return value must survive structured clone. See the module header for the full rationale.
  *
  * Never throws: an unsupported runtime, a failed start, a thrown function, and a lapsed deadline all
- * resolve to a {@link RunInWorkerResult}. The worker is terminated and the blob URL revoked on every path.
+ * resolve to a {@link WorkerRunResult}. The worker is terminated and the blob URL revoked on every path.
  */
-export declare function runInWorker<TArgs extends readonly unknown[], TValue>(fn: (...args: TArgs) => TValue | Promise<TValue>, args: TArgs, options?: RunInWorkerOptions): Promise<RunInWorkerResult<TValue>>;
+export declare function runInWorker<TArgs extends readonly unknown[], TValue>(fn: (...args: TArgs) => TValue | Promise<TValue>, args: TArgs, options?: RunInWorkerOptions): Promise<WorkerRunResult<TValue>>;

package/dist/foundation/workers/UseWorker.d.ts

@@ -1,7 +1,7 @@
 import { ShallowRef } from 'vue';
 import { WorkerApiOf, WorkerClient, WorkerClientOptions } from './WorkerClient';
 /** What {@link useWorker} returns. */
-export interface UseWorkerResult<TApi extends WorkerApiOf<TApi>> {
+export interface UseWorkerControls<TApi extends WorkerApiOf<TApi>> {
     /**
      * The typed client, or `null` before mount and in any runtime without `Worker`.
      *
@@ -18,11 +18,6 @@ export interface UseWorkerResult<TApi extends WorkerApiOf<TApi>> {
 /**
  * Owns a worker for the lifetime of the calling scope: created on mount, terminated on disposal.
  *
- * ```ts
- * const { client } = useWorker<MathApi>(() => new Worker(new URL('./math.worker.ts', import.meta.url), { type: 'module' }));
- * const sum = await client.value?.call('add', 2, 3);
- * ```
- *
  * The factory is invoked once per mount, so an inline arrow is the expected call shape.
  */
-export declare function useWorker<TApi extends WorkerApiOf<TApi>>(factory: () => Worker, options?: WorkerClientOptions): UseWorkerResult<TApi>;
+export declare function useWorker<TApi extends WorkerApiOf<TApi>>(factory: () => Worker, options?: WorkerClientOptions): UseWorkerControls<TApi>;

package/dist/foundation/workers/WorkerClient.d.ts

@@ -32,7 +32,7 @@ export interface WorkerCallOptions {
      * `byteLength === 0` and reading it throws. This is the single most surprising thing about the API and
      * is the price of the move — see the `withTransfer` docs for the full note.
      */
-    readonly transfer?: readonly Transferable[];
+    readonly transfer?: ReadonlyArray<Transferable>;
 }
 /** Tunes a client. */
 export interface WorkerClientOptions {
@@ -52,11 +52,14 @@ export interface WorkerClient<TApi extends WorkerApiOf<TApi>> {
      * elapses, the worker dies, or {@link WorkerClient.terminate} is called while this is in flight.
      */
     call<TMethod extends keyof TApi & string>(method: TMethod, ...args: Parameters<TApi[TMethod]>): Promise<Awaited<ReturnType<TApi[TMethod]>>>;
-    /** Calls `method` with per-call options — a deadline, a transfer list, or both. Otherwise identical to {@link WorkerClient.call}. */
+    /**
+     * Calls `method` with per-call options — a deadline, a transfer list, or both. Otherwise identical to
+     * {@link WorkerClient.call}.
+     */
     callWith<TMethod extends keyof TApi & string>(options: WorkerCallOptions, method: TMethod, ...args: Parameters<TApi[TMethod]>): Promise<Awaited<ReturnType<TApi[TMethod]>>>;
     /** The number of calls awaiting a reply — the observable that proves an exit path cleaned up after itself. */
     readonly pendingCount: number;
-    /** Whether {@link WorkerClient.terminate} has run. A terminated client rejects every further call rather than hanging. */
+    /** Whether {@link WorkerClient.terminate} has run. A terminated client rejects further calls rather than hanging. */
     readonly terminated: boolean;
     /**
      * Kills the worker and rejects every in-flight call. Idempotent.
@@ -72,12 +75,6 @@ export interface WorkerClient<TApi extends WorkerApiOf<TApi>> {
  * The worker must run {@link exposeWorkerApi} (or speak the same envelope). `TApi` is the shared contract:
  * declare it once, use it here and to type the handler map on the worker side.
  *
- * ```ts
- * interface MathApi { add(a: number, b: number): number }
- * const client = createWorkerClient<MathApi>(new Worker(new URL('./math.worker.ts', import.meta.url), { type: 'module' }));
- * await client.call('add', 2, 3); // 5
- * ```
- *
  * Takes an already-constructed `Worker` rather than a factory so it stays usable with any worker the
  * consumer's bundler produced, and so nothing in this module ever touches the `Worker` constructor — which
  * is what keeps it importable under SSR.

package/dist/foundation/workers/WorkerHost.d.ts

@@ -9,7 +9,7 @@ export interface WorkerScope {
     /** Unsubscribes a previously registered listener. */
     removeEventListener(type: 'message', listener: (event: MessageEvent) => void): void;
     /** Posts a reply back to the main thread, optionally transferring ownership of objects reachable from it. */
-    postMessage(message: unknown, transfer?: Transferable[]): void;
+    postMessage(message: unknown, transfer?: ReadonlyArray<Transferable>): void;
 }
 /** Constrains a handler map: method name → implementation, sync or async. */
 export type WorkerHandlerMap = Record<string, (...args: never[]) => unknown>;
@@ -41,7 +41,7 @@ export interface WorkerTransfer<TValue> {
     /** The value the client will receive — the wrapper itself is stripped before posting. */
     readonly value: TValue;
     /** The objects whose ownership moves to the main thread. */
-    readonly transfer: readonly Transferable[];
+    readonly transfer: ReadonlyArray<Transferable>;
 }
 /**
  * Marks a handler's result for transfer instead of a structured-clone copy — the return-path counterpart
@@ -66,7 +66,7 @@ export interface WorkerTransfer<TValue> {
  * The same neutering hits the CALLER when transferring into the worker via `callWith({ transfer })`: after
  * that call the caller's `ArrayBuffer` is the empty one.
  */
-export declare function withTransfer<TValue>(value: TValue, transfer: readonly Transferable[]): WorkerTransfer<TValue>;
+export declare function withTransfer<TValue>(value: TValue, transfer: ReadonlyArray<Transferable>): WorkerTransfer<TValue>;
 /**
  * Registers `handlers` as the worker's RPC surface and returns a disposer that unregisters them.
  *

package/dist/foundation/workers/WorkerProtocol.d.ts

@@ -17,7 +17,7 @@ export interface WorkerRequestMessage {
     /** The handler name to dispatch to on the worker side. */
     readonly method: string;
     /** The positional arguments, structured-cloned (or transferred) to the worker. */
-    readonly args: readonly unknown[];
+    readonly args: ReadonlyArray<unknown>;
 }
 /** Describes a reply carrying a handler's resolved value. */
 export interface WorkerSuccessMessage {
@@ -62,7 +62,7 @@ export declare function isWorkerRequestMessage(value: unknown): value is WorkerR
  */
 export declare function isWorkerResponseMessage(value: unknown): value is WorkerResponseMessage;
 /** Builds a request envelope. */
-export declare function createRequestMessage(id: number, method: string, args: readonly unknown[]): WorkerRequestMessage;
+export declare function createRequestMessage(id: number, method: string, args: ReadonlyArray<unknown>): WorkerRequestMessage;
 /** Builds a success reply. */
 export declare function createSuccessMessage(id: number, result: unknown): WorkerSuccessMessage;
 /** Builds a failure reply. */

package/dist/foundation/workers/WorkerRunFailureCode.d.ts

@@ -0,0 +1,6 @@
+/** Closed failure vocabulary for WorkerRunFailure. */
+export declare const WorkerRunFailureCode: {
+    readonly Unsupported: "unsupported";
+    readonly Failed: "failed";
+};
+export type WorkerRunFailureCode = (typeof WorkerRunFailureCode)[keyof typeof WorkerRunFailureCode];

package/dist/foundation/workers/index.d.ts

@@ -2,5 +2,6 @@ export { isWorkerSupported, isBlobWorkerSupported } from './WorkerSupport';
 export { WorkerMessageChannel, isWorkerRequestMessage, isWorkerResponseMessage, createRequestMessage, createSuccessMessage, createFailureMessage, createRequestIdAllocator, type WorkerRequestMessage, type WorkerSuccessMessage, type WorkerFailureMessage, type WorkerResponseMessage, } from './WorkerProtocol';
 export { createWorkerClient, type WorkerApiOf, type WorkerClient, type WorkerCallOptions, type WorkerClientOptions, } from './WorkerClient';
 export { exposeWorkerApi, withTransfer, WorkerTransferMarker, type WorkerScope, type WorkerHandlerMap, type WorkerHandlersOf, type WorkerTransfer, } from './WorkerHost';
-export { useWorker, type UseWorkerResult } from './UseWorker';
-export { runInWorker, type RunInWorkerResult, type RunInWorkerOptions } from './RunInWorker';
+export { useWorker, type UseWorkerControls } from './UseWorker';
+export { runInWorker, type WorkerRunFailure, type WorkerRunResult, type RunInWorkerOptions } from './RunInWorker';
+export { WorkerRunFailureCode } from './WorkerRunFailureCode';

package/dist/foundation/workers/index.js

@@ -1,5 +1,5 @@
-import { t as toError } from "../../chunks/ToError-CyTBsmLO.js";
-import { s as serializeError } from "../../chunks/SerializeError-CclP2jCW.js";
+import { t as toError } from "../../chunks/ToError-vXncXe19.js";
+import { s as serializeError } from "../../chunks/SerializeError-BzTdy-3I.js";
 import { shallowRef, onMounted, onScopeDispose } from "vue";
 function isWorkerSupported() {
   return typeof Worker === "function";
@@ -223,15 +223,15 @@ function isRecord(value) {
   return typeof value === "object" && value !== null;
 }
 async function runInWorker(fn, args, options) {
-  if (!isBlobWorkerSupported()) return { status: "unsupported" };
+  if (!isBlobWorkerSupported()) return { ok: false, failure: { status: "unsupported" } };
   let url;
   let worker;
+  let timer;
   try {
     url = URL.createObjectURL(new Blob([buildWorkerSource(fn.toString())], { type: "text/javascript" }));
     const instance = new Worker(url);
     worker = instance;
     const value = await new Promise((resolve, reject) => {
-      let timer;
       const done = () => {
         if (timer !== void 0) clearTimeout(timer);
       };
@@ -260,20 +260,30 @@ async function runInWorker(fn, args, options) {
         done();
         reject(toError(event.error ?? event.message ?? "Worker failed to start"));
       });
+      instance.addEventListener("messageerror", () => {
+        done();
+        reject(new Error("Worker reply could not be deserialized"));
+      });
       const transfer = options?.transfer;
       if (transfer !== void 0 && transfer.length > 0) instance.postMessage(args, [...transfer]);
       else instance.postMessage(args);
     });
-    return { status: "ok", value };
+    return { ok: true, value };
   } catch (error) {
-    return { status: "failed", error: toError(error) };
+    return { ok: false, failure: { status: "failed", error: toError(error) } };
   } finally {
+    if (timer !== void 0) clearTimeout(timer);
     worker?.terminate();
     if (url !== void 0) URL.revokeObjectURL(url);
   }
 }
+const WorkerRunFailureCode = {
+  Unsupported: "unsupported",
+  Failed: "failed"
+};
 export {
   WorkerMessageChannel,
+  WorkerRunFailureCode,
   WorkerTransferMarker,
   createFailureMessage,
   createRequestIdAllocator,