@hurraey/interval-virtualizer 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 HURRAEY
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,144 @@
-# Temporary Holding Version
+# Interval Virtualizer
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+숫자 축 위의 구간 데이터에서 화면과 겹치는 항목을 찾는 TypeScript 라이브러리입니다. 오디오·비디오 타임라인, 일정, 문자 범위처럼 시작·종료 좌표가 있는 데이터에 사용할 수 있습니다.
+
+구간 조회와 화면 범위 계산은 React나 DOM에 의존하지 않습니다. React 18·19용 구독 훅은 별도 진입점으로 제공합니다.
+
+## 설치
+
+Node.js 20 이상을 지원하며 ESM과 CommonJS, TypeScript 타입을 제공합니다.
+
+```sh
+npm install @hurraey/interval-virtualizer
+```
+
+React 훅을 사용할 때는 애플리케이션에 React 18.2 이상 또는 React 19가 필요합니다. 순수 계산 API만 사용하면 React를 설치할 필요가 없습니다.
+
+## 구간 조회
+
+```ts
+import { createIntervalIndex, queryIntervals } from '@hurraey/interval-virtualizer';
+
+const clips = [
+  { id: 'background', start: 0, end: 100 },
+  { id: 'effect', start: 75, end: 78 },
+  { id: 'later', start: 110, end: 120 },
+];
+
+const index = createIntervalIndex(clips);
+const result = queryIntervals(index, { start: 70, end: 80 });
+
+console.log(result.intervals.map((clip) => clip.id));
+// ['background', 'effect']
+```
+
+- 시작 좌표와 종료 좌표는 같은 단위를 사용합니다. 초, 프레임, 픽셀, 문자 위치 모두 가능합니다.
+- 조회 범위의 경계에 닿는 구간과 길이가 0인 구간도 포함합니다. 겹침 조건은 `start <= range.end && end >= range.start`입니다.
+- 결과는 입력 순서를 유지하며 원래 객체를 반환합니다. 입력 배열을 정렬하거나 수정하지 않습니다.
+- 음수 좌표를 지원합니다. 유한한 숫자가 아닌 좌표와 `end < start`인 항목은 인덱스에서 제외합니다.
+- 잘못된 조회 범위에는 빈 배열과 `inspectedIntervalCount: 0`을 반환합니다.
+
+인덱스는 생성 시점의 좌표를 보관합니다. 항목을 추가·삭제하거나 시작·종료 좌표를 바꾸면 다시 생성해야 합니다. 스크롤과 줌만 바뀌면 같은 인덱스를 재사용합니다.
+
+### 조회 방식과 비용
+
+시작 좌표순으로 정렬한 배열에서 이진 탐색으로 후보의 끝을 찾습니다. 각 하위 구간의 최대 종료 좌표를 저장한 세그먼트 트리를 따라가며, 화면 전에 모두 끝난 구간은 건너뜁니다.
+
+인덱스 생성에는 정렬 비용과 항목 수에 비례하는 메모리가 필요합니다. 조회 후 입력 순서를 복원하는 정렬도 수행하므로 전체 조회가 항상 `O(log N)`에 끝나는 것은 아닙니다.
+
+`inspectedIntervalCount`는 실제로 내려가 검사한 개별 항목 수입니다. 이진 탐색 비교, 트리 노드 방문, 정렬 비용이나 실행 시간을 나타내지 않습니다.
+
+## 화면 범위 계산
+
+```ts
+import { getVirtualViewportRange } from '@hurraey/interval-virtualizer';
+
+const range = getVirtualViewportRange({
+  offset: 4_100,
+  viewportSize: 800,
+  contentSize: 10_000,
+  chunkSize: 1_000,
+  overscanChunks: 2,
+  padding: 8,
+});
+
+console.log(range);
+// { start: 1992, end: 7008 }
+```
+
+`offset`은 현재 스크롤 위치이고 `viewportSize`와 `contentSize`는 각각 화면과 전체 콘텐츠의 크기입니다. `chunkSize`는 조회 범위를 묶는 단위입니다. 같은 청크 안에서는 작은 스크롤 변화에도 같은 범위를 반환할 수 있습니다.
+
+`overscanChunks`는 양옆에 추가할 청크 수이며 기본값은 0입니다. 소수는 내림합니다. `padding`은 청크 바깥에 더할 여유 크기이며 기본값은 0입니다. 청크 수를 제외한 옵션은 모두 같은 좌표 단위를 사용합니다.
+
+결과는 콘텐츠 범위를 넘지 않습니다. 화면·콘텐츠·청크 크기가 0 이하이거나 입력이 유효하지 않으면 `null`을 반환합니다.
+
+픽셀 범위를 초 단위 인덱스에 조회하려면 두 경계를 초당 픽셀 수로 나눠 사용합니다.
+
+## React 연결
+
+`@hurraey/interval-virtualizer/react`의 `useVirtualViewportRange`는 브라우저에서 사용합니다. 서버 렌더링용 스냅샷은 제공하지 않습니다. Next.js 등에서는 클라이언트에서 마운트된 영역에 연결하세요.
+
+```tsx
+import { useCallback, useRef } from 'react';
+import { useVirtualViewportRange } from '@hurraey/interval-virtualizer/react';
+
+export function ScrollRange() {
+  const offsetRef = useRef(0);
+  const listenersRef = useRef(new Set<() => void>());
+  const subscribe = useCallback((listener: () => void) => {
+    listenersRef.current.add(listener);
+    return () => {
+      listenersRef.current.delete(listener);
+    };
+  }, []);
+
+  const range = useVirtualViewportRange({
+    offsetRef,
+    subscribe,
+    viewportSize: 800,
+    contentSize: 10_000,
+    chunkSize: 1_000,
+    overscanChunks: 1,
+  });
+
+  return (
+    <div
+      style={{ width: 800, overflowX: 'auto' }}
+      onScroll={(event) => {
+        offsetRef.current = event.currentTarget.scrollLeft;
+        listenersRef.current.forEach((listener) => listener());
+      }}
+    >
+      <div style={{ width: 10_000 }}>{range ? `${range.start} ~ ${range.end}` : '화면 크기 측정 전'}</div>
+    </div>
+  );
+}
+```
+
+스크롤을 처리하는 쪽에서 ref를 먼저 갱신한 뒤 구독자에게 알립니다. `subscribe`는 구독 해제 함수를 반환해야 합니다. 훅은 계산된 범위가 같으면 같은 스냅샷 객체를 반환하며, 언마운트할 때 구독을 해제합니다.
+
+DOM 크기 측정, 스크롤 이벤트 등록, `requestAnimationFrame` 예약, 실제 UI 렌더링은 사용하는 애플리케이션에서 담당합니다. 선택 중인 항목을 화면 밖에서도 유지하는 정책 역시 애플리케이션에서 처리합니다.
+
+## 공개 API
+
+- `createIntervalIndex<T extends Interval>(intervals)` - 구간 인덱스를 생성합니다.
+- `queryIntervals(index, range)` - `{ intervals, inspectedIntervalCount }`를 반환합니다.
+- `getVirtualViewportRange(options)` - `{ start, end }` 또는 `null`을 반환합니다.
+- `useVirtualViewportRange(options)` - React에서 외부 스크롤 알림을 구독합니다. `/react`에서 가져옵니다.
+
+루트 진입점은 `Interval`, `IntervalIndex`, `IntervalQueryRange`, `IntervalQueryResult`, `VirtualViewportOptions` 타입을 제공합니다. `/react`는 `VirtualViewportSubscriptionOptions` 타입을 제공합니다.
+
+## 개발과 검증
+
+저장소 루트에서 실행합니다.
+
+```sh
+npm ci
+npm run check
+```
+
+구간 조회·화면 범위·React 구독 테스트, 타입 검사, ESM·CommonJS 빌드와 실제 패키지 설치 검증을 실행합니다. 패키지 설치 검증은 임시 디렉터리에서 실행하고 종료 시 삭제합니다.
+
+## 라이선스
+
+[MIT](./LICENSE)

package/dist/index.cjs

@@ -0,0 +1,136 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  createIntervalIndex: () => createIntervalIndex,
+  getVirtualViewportRange: () => getVirtualViewportRange,
+  queryIntervals: () => queryIntervals
+});
+module.exports = __toCommonJS(src_exports);
+
+// src/interval-index.ts
+function findFirstIntervalStartingAfter(sortedIntervals, target) {
+  let low = 0;
+  let high = sortedIntervals.length;
+  while (low < high) {
+    const middle = low + Math.floor((high - low) / 2);
+    if (sortedIntervals[middle].start <= target) {
+      low = middle + 1;
+    } else {
+      high = middle;
+    }
+  }
+  return low;
+}
+function createMaxEndTree(sortedIntervals) {
+  let leafOffset = 1;
+  while (leafOffset < sortedIntervals.length) {
+    leafOffset *= 2;
+  }
+  const maxEndTree = Array(leafOffset * 2).fill(Number.NEGATIVE_INFINITY);
+  for (let index = 0; index < sortedIntervals.length; index += 1) {
+    maxEndTree[leafOffset + index] = sortedIntervals[index].end;
+  }
+  for (let nodeIndex = leafOffset - 1; nodeIndex > 0; nodeIndex -= 1) {
+    maxEndTree[nodeIndex] = Math.max(maxEndTree[nodeIndex * 2], maxEndTree[nodeIndex * 2 + 1]);
+  }
+  return { maxEndTree, leafOffset };
+}
+function createIntervalIndex(intervals) {
+  const sortedIntervals = intervals.map((interval, originalIndex) => ({
+    interval,
+    start: interval.start,
+    end: interval.end,
+    originalIndex
+  })).filter(
+    (indexedInterval) => Number.isFinite(indexedInterval.start) && Number.isFinite(indexedInterval.end) && indexedInterval.end >= indexedInterval.start
+  ).sort((left, right) => left.start - right.start || left.originalIndex - right.originalIndex);
+  const { maxEndTree, leafOffset } = createMaxEndTree(sortedIntervals);
+  return { sortedIntervals, maxEndTree, leafOffset };
+}
+function queryIntervals(index, range) {
+  if (!Number.isFinite(range.start) || !Number.isFinite(range.end) || range.end < range.start) {
+    return { intervals: [], inspectedIntervalCount: 0 };
+  }
+  const candidateEndIndex = findFirstIntervalStartingAfter(index.sortedIntervals, range.end);
+  if (candidateEndIndex === 0) {
+    return { intervals: [], inspectedIntervalCount: 0 };
+  }
+  const visibleIntervals = [];
+  const pendingNodes = [{ nodeIndex: 1, intervalStart: 0, intervalEnd: index.leafOffset }];
+  let inspectedIntervalCount = 0;
+  while (pendingNodes.length > 0) {
+    const currentNode = pendingNodes.pop();
+    if (!currentNode || currentNode.intervalStart >= candidateEndIndex || index.maxEndTree[currentNode.nodeIndex] < range.start) {
+      continue;
+    }
+    if (currentNode.intervalEnd - currentNode.intervalStart > 1) {
+      const middle = currentNode.intervalStart + Math.floor((currentNode.intervalEnd - currentNode.intervalStart) / 2);
+      pendingNodes.push(
+        { nodeIndex: currentNode.nodeIndex * 2 + 1, intervalStart: middle, intervalEnd: currentNode.intervalEnd },
+        { nodeIndex: currentNode.nodeIndex * 2, intervalStart: currentNode.intervalStart, intervalEnd: middle }
+      );
+      continue;
+    }
+    const indexedInterval = index.sortedIntervals[currentNode.intervalStart];
+    if (!indexedInterval) {
+      continue;
+    }
+    inspectedIntervalCount += 1;
+    if (indexedInterval.end >= range.start) {
+      visibleIntervals.push(indexedInterval);
+    }
+  }
+  visibleIntervals.sort((left, right) => left.originalIndex - right.originalIndex);
+  return {
+    intervals: visibleIntervals.map((indexedInterval) => indexedInterval.interval),
+    inspectedIntervalCount
+  };
+}
+
+// src/viewport-range.ts
+function getVirtualViewportRange({
+  offset,
+  viewportSize,
+  contentSize,
+  chunkSize,
+  overscanChunks = 0,
+  padding = 0
+}) {
+  if (![offset, viewportSize, contentSize, chunkSize, overscanChunks, padding].every(Number.isFinite) || viewportSize <= 0 || contentSize <= 0 || chunkSize <= 0 || overscanChunks < 0 || padding < 0) {
+    return null;
+  }
+  const clampedOffset = Math.max(0, Math.min(offset, contentSize - viewportSize));
+  const overscan = Math.floor(overscanChunks);
+  const firstChunk = Math.max(0, Math.floor(clampedOffset / chunkSize) - overscan);
+  const endChunk = Math.ceil((clampedOffset + viewportSize) / chunkSize) + overscan;
+  return {
+    start: Math.max(0, firstChunk * chunkSize - padding),
+    end: Math.min(contentSize, endChunk * chunkSize + padding)
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createIntervalIndex,
+  getVirtualViewportRange,
+  queryIntervals
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/interval-index.ts","../src/viewport-range.ts"],"sourcesContent":["export { createIntervalIndex, queryIntervals } from './interval-index';\nexport type { Interval, IntervalIndex, IntervalQueryRange, IntervalQueryResult } from './interval-index';\nexport { getVirtualViewportRange } from './viewport-range';\nexport type { VirtualViewportOptions } from './viewport-range';\n","export interface Interval {\n  start: number;\n  end: number;\n}\n\ninterface IndexedInterval<TInterval extends Interval> {\n  interval: TInterval;\n  start: number;\n  end: number;\n  originalIndex: number;\n}\n\nexport interface IntervalIndex<TInterval extends Interval> {\n  readonly sortedIntervals: ReadonlyArray<IndexedInterval<TInterval>>;\n  readonly maxEndTree: readonly number[];\n  readonly leafOffset: number;\n}\n\nexport interface IntervalQueryRange {\n  start: number;\n  end: number;\n}\n\nexport interface IntervalQueryResult<TInterval extends Interval> {\n  intervals: TInterval[];\n  inspectedIntervalCount: number;\n}\n\nfunction findFirstIntervalStartingAfter<TInterval extends Interval>(\n  sortedIntervals: ReadonlyArray<IndexedInterval<TInterval>>,\n  target: number,\n): number {\n  let low = 0;\n  let high = sortedIntervals.length;\n\n  while (low < high) {\n    const middle = low + Math.floor((high - low) / 2);\n    if (sortedIntervals[middle].start <= target) {\n      low = middle + 1;\n    } else {\n      high = middle;\n    }\n  }\n\n  return low;\n}\n\nfunction createMaxEndTree<TInterval extends Interval>(\n  sortedIntervals: ReadonlyArray<IndexedInterval<TInterval>>,\n): {\n  maxEndTree: number[];\n  leafOffset: number;\n} {\n  let leafOffset = 1;\n  while (leafOffset < sortedIntervals.length) {\n    leafOffset *= 2;\n  }\n\n  const maxEndTree = Array<number>(leafOffset * 2).fill(Number.NEGATIVE_INFINITY);\n  for (let index = 0; index < sortedIntervals.length; index += 1) {\n    maxEndTree[leafOffset + index] = sortedIntervals[index].end;\n  }\n\n  for (let nodeIndex = leafOffset - 1; nodeIndex > 0; nodeIndex -= 1) {\n    maxEndTree[nodeIndex] = Math.max(maxEndTree[nodeIndex * 2], maxEndTree[nodeIndex * 2 + 1]);\n  }\n\n  return { maxEndTree, leafOffset };\n}\n\nexport function createIntervalIndex<TInterval extends Interval>(\n  intervals: readonly TInterval[],\n): IntervalIndex<TInterval> {\n  const sortedIntervals = intervals\n    .map((interval, originalIndex) => ({\n      interval,\n      start: interval.start,\n      end: interval.end,\n      originalIndex,\n    }))\n    .filter(\n      (indexedInterval) =>\n        Number.isFinite(indexedInterval.start) &&\n        Number.isFinite(indexedInterval.end) &&\n        indexedInterval.end >= indexedInterval.start,\n    )\n    .sort((left, right) => left.start - right.start || left.originalIndex - right.originalIndex);\n\n  // 하위 트리별 최대 종료 시간을 저장해 긴 구간 하나가 앞쪽의 짧은 구간 전체를 후보로 만들지 않게 한다.\n  const { maxEndTree, leafOffset } = createMaxEndTree(sortedIntervals);\n  return { sortedIntervals, maxEndTree, leafOffset };\n}\n\nexport function queryIntervals<TInterval extends Interval>(\n  index: IntervalIndex<TInterval>,\n  range: IntervalQueryRange,\n): IntervalQueryResult<TInterval> {\n  if (!Number.isFinite(range.start) || !Number.isFinite(range.end) || range.end < range.start) {\n    return { intervals: [], inspectedIntervalCount: 0 };\n  }\n\n  const candidateEndIndex = findFirstIntervalStartingAfter(index.sortedIntervals, range.end);\n  if (candidateEndIndex === 0) {\n    return { intervals: [], inspectedIntervalCount: 0 };\n  }\n\n  const visibleIntervals: Array<IndexedInterval<TInterval>> = [];\n  const pendingNodes = [{ nodeIndex: 1, intervalStart: 0, intervalEnd: index.leafOffset }];\n  let inspectedIntervalCount = 0;\n\n  while (pendingNodes.length > 0) {\n    const currentNode = pendingNodes.pop();\n    if (\n      !currentNode ||\n      currentNode.intervalStart >= candidateEndIndex ||\n      index.maxEndTree[currentNode.nodeIndex] < range.start\n    ) {\n      continue;\n    }\n\n    if (currentNode.intervalEnd - currentNode.intervalStart > 1) {\n      const middle = currentNode.intervalStart + Math.floor((currentNode.intervalEnd - currentNode.intervalStart) / 2);\n      pendingNodes.push(\n        { nodeIndex: currentNode.nodeIndex * 2 + 1, intervalStart: middle, intervalEnd: currentNode.intervalEnd },\n        { nodeIndex: currentNode.nodeIndex * 2, intervalStart: currentNode.intervalStart, intervalEnd: middle },\n      );\n      continue;\n    }\n\n    const indexedInterval = index.sortedIntervals[currentNode.intervalStart];\n    if (!indexedInterval) {\n      continue;\n    }\n\n    inspectedIntervalCount += 1;\n    if (indexedInterval.end >= range.start) {\n      visibleIntervals.push(indexedInterval);\n    }\n  }\n\n  visibleIntervals.sort((left, right) => left.originalIndex - right.originalIndex);\n\n  return {\n    intervals: visibleIntervals.map((indexedInterval) => indexedInterval.interval),\n    inspectedIntervalCount,\n  };\n}\n","import type { Interval } from './interval-index';\n\nexport interface VirtualViewportOptions {\n  offset: number;\n  viewportSize: number;\n  contentSize: number;\n  chunkSize: number;\n  overscanChunks?: number;\n  padding?: number;\n}\n\n/** 같은 청크 안에서는 조회 범위를 유지해 작은 스크롤마다 항목을 다시 조회하지 않는다. */\nexport function getVirtualViewportRange({\n  offset,\n  viewportSize,\n  contentSize,\n  chunkSize,\n  overscanChunks = 0,\n  padding = 0,\n}: VirtualViewportOptions): Interval | null {\n  if (\n    ![offset, viewportSize, contentSize, chunkSize, overscanChunks, padding].every(Number.isFinite) ||\n    viewportSize <= 0 ||\n    contentSize <= 0 ||\n    chunkSize <= 0 ||\n    overscanChunks < 0 ||\n    padding < 0\n  ) {\n    return null;\n  }\n\n  const clampedOffset = Math.max(0, Math.min(offset, contentSize - viewportSize));\n  const overscan = Math.floor(overscanChunks);\n  const firstChunk = Math.max(0, Math.floor(clampedOffset / chunkSize) - overscan);\n  const endChunk = Math.ceil((clampedOffset + viewportSize) / chunkSize) + overscan;\n\n  return {\n    start: Math.max(0, firstChunk * chunkSize - padding),\n    end: Math.min(contentSize, endChunk * chunkSize + padding),\n  };\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,38 @@
+interface Interval {
+    start: number;
+    end: number;
+}
+interface IndexedInterval<TInterval extends Interval> {
+    interval: TInterval;
+    start: number;
+    end: number;
+    originalIndex: number;
+}
+interface IntervalIndex<TInterval extends Interval> {
+    readonly sortedIntervals: ReadonlyArray<IndexedInterval<TInterval>>;
+    readonly maxEndTree: readonly number[];
+    readonly leafOffset: number;
+}
+interface IntervalQueryRange {
+    start: number;
+    end: number;
+}
+interface IntervalQueryResult<TInterval extends Interval> {
+    intervals: TInterval[];
+    inspectedIntervalCount: number;
+}
+declare function createIntervalIndex<TInterval extends Interval>(intervals: readonly TInterval[]): IntervalIndex<TInterval>;
+declare function queryIntervals<TInterval extends Interval>(index: IntervalIndex<TInterval>, range: IntervalQueryRange): IntervalQueryResult<TInterval>;
+
+interface VirtualViewportOptions {
+    offset: number;
+    viewportSize: number;
+    contentSize: number;
+    chunkSize: number;
+    overscanChunks?: number;
+    padding?: number;
+}
+/** 같은 청크 안에서는 조회 범위를 유지해 작은 스크롤마다 항목을 다시 조회하지 않는다. */
+declare function getVirtualViewportRange({ offset, viewportSize, contentSize, chunkSize, overscanChunks, padding, }: VirtualViewportOptions): Interval | null;
+
+export { type Interval, type IntervalIndex, type IntervalQueryRange, type IntervalQueryResult, type VirtualViewportOptions, createIntervalIndex, getVirtualViewportRange, queryIntervals };

package/dist/index.d.ts

@@ -0,0 +1,38 @@
+interface Interval {
+    start: number;
+    end: number;
+}
+interface IndexedInterval<TInterval extends Interval> {
+    interval: TInterval;
+    start: number;
+    end: number;
+    originalIndex: number;
+}
+interface IntervalIndex<TInterval extends Interval> {
+    readonly sortedIntervals: ReadonlyArray<IndexedInterval<TInterval>>;
+    readonly maxEndTree: readonly number[];
+    readonly leafOffset: number;
+}
+interface IntervalQueryRange {
+    start: number;
+    end: number;
+}
+interface IntervalQueryResult<TInterval extends Interval> {
+    intervals: TInterval[];
+    inspectedIntervalCount: number;
+}
+declare function createIntervalIndex<TInterval extends Interval>(intervals: readonly TInterval[]): IntervalIndex<TInterval>;
+declare function queryIntervals<TInterval extends Interval>(index: IntervalIndex<TInterval>, range: IntervalQueryRange): IntervalQueryResult<TInterval>;
+
+interface VirtualViewportOptions {
+    offset: number;
+    viewportSize: number;
+    contentSize: number;
+    chunkSize: number;
+    overscanChunks?: number;
+    padding?: number;
+}
+/** 같은 청크 안에서는 조회 범위를 유지해 작은 스크롤마다 항목을 다시 조회하지 않는다. */
+declare function getVirtualViewportRange({ offset, viewportSize, contentSize, chunkSize, overscanChunks, padding, }: VirtualViewportOptions): Interval | null;
+
+export { type Interval, type IntervalIndex, type IntervalQueryRange, type IntervalQueryResult, type VirtualViewportOptions, createIntervalIndex, getVirtualViewportRange, queryIntervals };

package/dist/index.js

@@ -0,0 +1,107 @@
+// src/interval-index.ts
+function findFirstIntervalStartingAfter(sortedIntervals, target) {
+  let low = 0;
+  let high = sortedIntervals.length;
+  while (low < high) {
+    const middle = low + Math.floor((high - low) / 2);
+    if (sortedIntervals[middle].start <= target) {
+      low = middle + 1;
+    } else {
+      high = middle;
+    }
+  }
+  return low;
+}
+function createMaxEndTree(sortedIntervals) {
+  let leafOffset = 1;
+  while (leafOffset < sortedIntervals.length) {
+    leafOffset *= 2;
+  }
+  const maxEndTree = Array(leafOffset * 2).fill(Number.NEGATIVE_INFINITY);
+  for (let index = 0; index < sortedIntervals.length; index += 1) {
+    maxEndTree[leafOffset + index] = sortedIntervals[index].end;
+  }
+  for (let nodeIndex = leafOffset - 1; nodeIndex > 0; nodeIndex -= 1) {
+    maxEndTree[nodeIndex] = Math.max(maxEndTree[nodeIndex * 2], maxEndTree[nodeIndex * 2 + 1]);
+  }
+  return { maxEndTree, leafOffset };
+}
+function createIntervalIndex(intervals) {
+  const sortedIntervals = intervals.map((interval, originalIndex) => ({
+    interval,
+    start: interval.start,
+    end: interval.end,
+    originalIndex
+  })).filter(
+    (indexedInterval) => Number.isFinite(indexedInterval.start) && Number.isFinite(indexedInterval.end) && indexedInterval.end >= indexedInterval.start
+  ).sort((left, right) => left.start - right.start || left.originalIndex - right.originalIndex);
+  const { maxEndTree, leafOffset } = createMaxEndTree(sortedIntervals);
+  return { sortedIntervals, maxEndTree, leafOffset };
+}
+function queryIntervals(index, range) {
+  if (!Number.isFinite(range.start) || !Number.isFinite(range.end) || range.end < range.start) {
+    return { intervals: [], inspectedIntervalCount: 0 };
+  }
+  const candidateEndIndex = findFirstIntervalStartingAfter(index.sortedIntervals, range.end);
+  if (candidateEndIndex === 0) {
+    return { intervals: [], inspectedIntervalCount: 0 };
+  }
+  const visibleIntervals = [];
+  const pendingNodes = [{ nodeIndex: 1, intervalStart: 0, intervalEnd: index.leafOffset }];
+  let inspectedIntervalCount = 0;
+  while (pendingNodes.length > 0) {
+    const currentNode = pendingNodes.pop();
+    if (!currentNode || currentNode.intervalStart >= candidateEndIndex || index.maxEndTree[currentNode.nodeIndex] < range.start) {
+      continue;
+    }
+    if (currentNode.intervalEnd - currentNode.intervalStart > 1) {
+      const middle = currentNode.intervalStart + Math.floor((currentNode.intervalEnd - currentNode.intervalStart) / 2);
+      pendingNodes.push(
+        { nodeIndex: currentNode.nodeIndex * 2 + 1, intervalStart: middle, intervalEnd: currentNode.intervalEnd },
+        { nodeIndex: currentNode.nodeIndex * 2, intervalStart: currentNode.intervalStart, intervalEnd: middle }
+      );
+      continue;
+    }
+    const indexedInterval = index.sortedIntervals[currentNode.intervalStart];
+    if (!indexedInterval) {
+      continue;
+    }
+    inspectedIntervalCount += 1;
+    if (indexedInterval.end >= range.start) {
+      visibleIntervals.push(indexedInterval);
+    }
+  }
+  visibleIntervals.sort((left, right) => left.originalIndex - right.originalIndex);
+  return {
+    intervals: visibleIntervals.map((indexedInterval) => indexedInterval.interval),
+    inspectedIntervalCount
+  };
+}
+
+// src/viewport-range.ts
+function getVirtualViewportRange({
+  offset,
+  viewportSize,
+  contentSize,
+  chunkSize,
+  overscanChunks = 0,
+  padding = 0
+}) {
+  if (![offset, viewportSize, contentSize, chunkSize, overscanChunks, padding].every(Number.isFinite) || viewportSize <= 0 || contentSize <= 0 || chunkSize <= 0 || overscanChunks < 0 || padding < 0) {
+    return null;
+  }
+  const clampedOffset = Math.max(0, Math.min(offset, contentSize - viewportSize));
+  const overscan = Math.floor(overscanChunks);
+  const firstChunk = Math.max(0, Math.floor(clampedOffset / chunkSize) - overscan);
+  const endChunk = Math.ceil((clampedOffset + viewportSize) / chunkSize) + overscan;
+  return {
+    start: Math.max(0, firstChunk * chunkSize - padding),
+    end: Math.min(contentSize, endChunk * chunkSize + padding)
+  };
+}
+export {
+  createIntervalIndex,
+  getVirtualViewportRange,
+  queryIntervals
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/interval-index.ts","../src/viewport-range.ts"],"sourcesContent":["export interface Interval {\n  start: number;\n  end: number;\n}\n\ninterface IndexedInterval<TInterval extends Interval> {\n  interval: TInterval;\n  start: number;\n  end: number;\n  originalIndex: number;\n}\n\nexport interface IntervalIndex<TInterval extends Interval> {\n  readonly sortedIntervals: ReadonlyArray<IndexedInterval<TInterval>>;\n  readonly maxEndTree: readonly number[];\n  readonly leafOffset: number;\n}\n\nexport interface IntervalQueryRange {\n  start: number;\n  end: number;\n}\n\nexport interface IntervalQueryResult<TInterval extends Interval> {\n  intervals: TInterval[];\n  inspectedIntervalCount: number;\n}\n\nfunction findFirstIntervalStartingAfter<TInterval extends Interval>(\n  sortedIntervals: ReadonlyArray<IndexedInterval<TInterval>>,\n  target: number,\n): number {\n  let low = 0;\n  let high = sortedIntervals.length;\n\n  while (low < high) {\n    const middle = low + Math.floor((high - low) / 2);\n    if (sortedIntervals[middle].start <= target) {\n      low = middle + 1;\n    } else {\n      high = middle;\n    }\n  }\n\n  return low;\n}\n\nfunction createMaxEndTree<TInterval extends Interval>(\n  sortedIntervals: ReadonlyArray<IndexedInterval<TInterval>>,\n): {\n  maxEndTree: number[];\n  leafOffset: number;\n} {\n  let leafOffset = 1;\n  while (leafOffset < sortedIntervals.length) {\n    leafOffset *= 2;\n  }\n\n  const maxEndTree = Array<number>(leafOffset * 2).fill(Number.NEGATIVE_INFINITY);\n  for (let index = 0; index < sortedIntervals.length; index += 1) {\n    maxEndTree[leafOffset + index] = sortedIntervals[index].end;\n  }\n\n  for (let nodeIndex = leafOffset - 1; nodeIndex > 0; nodeIndex -= 1) {\n    maxEndTree[nodeIndex] = Math.max(maxEndTree[nodeIndex * 2], maxEndTree[nodeIndex * 2 + 1]);\n  }\n\n  return { maxEndTree, leafOffset };\n}\n\nexport function createIntervalIndex<TInterval extends Interval>(\n  intervals: readonly TInterval[],\n): IntervalIndex<TInterval> {\n  const sortedIntervals = intervals\n    .map((interval, originalIndex) => ({\n      interval,\n      start: interval.start,\n      end: interval.end,\n      originalIndex,\n    }))\n    .filter(\n      (indexedInterval) =>\n        Number.isFinite(indexedInterval.start) &&\n        Number.isFinite(indexedInterval.end) &&\n        indexedInterval.end >= indexedInterval.start,\n    )\n    .sort((left, right) => left.start - right.start || left.originalIndex - right.originalIndex);\n\n  // 하위 트리별 최대 종료 시간을 저장해 긴 구간 하나가 앞쪽의 짧은 구간 전체를 후보로 만들지 않게 한다.\n  const { maxEndTree, leafOffset } = createMaxEndTree(sortedIntervals);\n  return { sortedIntervals, maxEndTree, leafOffset };\n}\n\nexport function queryIntervals<TInterval extends Interval>(\n  index: IntervalIndex<TInterval>,\n  range: IntervalQueryRange,\n): IntervalQueryResult<TInterval> {\n  if (!Number.isFinite(range.start) || !Number.isFinite(range.end) || range.end < range.start) {\n    return { intervals: [], inspectedIntervalCount: 0 };\n  }\n\n  const candidateEndIndex = findFirstIntervalStartingAfter(index.sortedIntervals, range.end);\n  if (candidateEndIndex === 0) {\n    return { intervals: [], inspectedIntervalCount: 0 };\n  }\n\n  const visibleIntervals: Array<IndexedInterval<TInterval>> = [];\n  const pendingNodes = [{ nodeIndex: 1, intervalStart: 0, intervalEnd: index.leafOffset }];\n  let inspectedIntervalCount = 0;\n\n  while (pendingNodes.length > 0) {\n    const currentNode = pendingNodes.pop();\n    if (\n      !currentNode ||\n      currentNode.intervalStart >= candidateEndIndex ||\n      index.maxEndTree[currentNode.nodeIndex] < range.start\n    ) {\n      continue;\n    }\n\n    if (currentNode.intervalEnd - currentNode.intervalStart > 1) {\n      const middle = currentNode.intervalStart + Math.floor((currentNode.intervalEnd - currentNode.intervalStart) / 2);\n      pendingNodes.push(\n        { nodeIndex: currentNode.nodeIndex * 2 + 1, intervalStart: middle, intervalEnd: currentNode.intervalEnd },\n        { nodeIndex: currentNode.nodeIndex * 2, intervalStart: currentNode.intervalStart, intervalEnd: middle },\n      );\n      continue;\n    }\n\n    const indexedInterval = index.sortedIntervals[currentNode.intervalStart];\n    if (!indexedInterval) {\n      continue;\n    }\n\n    inspectedIntervalCount += 1;\n    if (indexedInterval.end >= range.start) {\n      visibleIntervals.push(indexedInterval);\n    }\n  }\n\n  visibleIntervals.sort((left, right) => left.originalIndex - right.originalIndex);\n\n  return {\n    intervals: visibleIntervals.map((indexedInterval) => indexedInterval.interval),\n    inspectedIntervalCount,\n  };\n}\n","import type { Interval } from './interval-index';\n\nexport interface VirtualViewportOptions {\n  offset: number;\n  viewportSize: number;\n  contentSize: number;\n  chunkSize: number;\n  overscanChunks?: number;\n  padding?: number;\n}\n\n/** 같은 청크 안에서는 조회 범위를 유지해 작은 스크롤마다 항목을 다시 조회하지 않는다. */\nexport function getVirtualViewportRange({\n  offset,\n  viewportSize,\n  contentSize,\n  chunkSize,\n  overscanChunks = 0,\n  padding = 0,\n}: VirtualViewportOptions): Interval | null {\n  if (\n    ![offset, viewportSize, contentSize, chunkSize, overscanChunks, padding].every(Number.isFinite) ||\n    viewportSize <= 0 ||\n    contentSize <= 0 ||\n    chunkSize <= 0 ||\n    overscanChunks < 0 ||\n    padding < 0\n  ) {\n    return null;\n  }\n\n  const clampedOffset = Math.max(0, Math.min(offset, contentSize - viewportSize));\n  const overscan = Math.floor(overscanChunks);\n  const firstChunk = Math.max(0, Math.floor(clampedOffset / chunkSize) - overscan);\n  const endChunk = Math.ceil((clampedOffset + viewportSize) / chunkSize) + overscan;\n\n  return {\n    start: Math.max(0, firstChunk * chunkSize - padding),\n    end: Math.min(contentSize, endChunk * chunkSize + padding),\n  };\n}\n"],"mappings":"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","names":[]}

package/dist/react/index.cjs

@@ -0,0 +1,85 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/react/index.ts
+var react_exports = {};
+__export(react_exports, {
+  useVirtualViewportRange: () => useVirtualViewportRange
+});
+module.exports = __toCommonJS(react_exports);
+
+// src/react/use-virtual-viewport-range.ts
+var import_react = require("react");
+
+// src/viewport-range.ts
+function getVirtualViewportRange({
+  offset,
+  viewportSize,
+  contentSize,
+  chunkSize,
+  overscanChunks = 0,
+  padding = 0
+}) {
+  if (![offset, viewportSize, contentSize, chunkSize, overscanChunks, padding].every(Number.isFinite) || viewportSize <= 0 || contentSize <= 0 || chunkSize <= 0 || overscanChunks < 0 || padding < 0) {
+    return null;
+  }
+  const clampedOffset = Math.max(0, Math.min(offset, contentSize - viewportSize));
+  const overscan = Math.floor(overscanChunks);
+  const firstChunk = Math.max(0, Math.floor(clampedOffset / chunkSize) - overscan);
+  const endChunk = Math.ceil((clampedOffset + viewportSize) / chunkSize) + overscan;
+  return {
+    start: Math.max(0, firstChunk * chunkSize - padding),
+    end: Math.min(contentSize, endChunk * chunkSize + padding)
+  };
+}
+
+// src/react/use-virtual-viewport-range.ts
+function createViewportSnapshotReader({
+  offsetRef,
+  ...options
+}) {
+  let snapshot = null;
+  return () => {
+    const next = getVirtualViewportRange({ ...options, offset: offsetRef?.current ?? 0 });
+    if (snapshot?.start !== next?.start || snapshot?.end !== next?.end) {
+      snapshot = next;
+    }
+    return snapshot;
+  };
+}
+function useVirtualViewportRange({
+  offsetRef,
+  subscribe,
+  viewportSize,
+  contentSize,
+  chunkSize,
+  overscanChunks = 0,
+  padding = 0
+}) {
+  const getSnapshot = (0, import_react.useMemo)(
+    () => createViewportSnapshotReader({ offsetRef, viewportSize, contentSize, chunkSize, overscanChunks, padding }),
+    [offsetRef, viewportSize, contentSize, chunkSize, overscanChunks, padding]
+  );
+  return (0, import_react.useSyncExternalStore)(subscribe, getSnapshot);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  useVirtualViewportRange
+});
+//# sourceMappingURL=index.cjs.map

package/dist/react/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/react/index.ts","../../src/react/use-virtual-viewport-range.ts","../../src/viewport-range.ts"],"sourcesContent":["export { useVirtualViewportRange } from './use-virtual-viewport-range';\nexport type { VirtualViewportSubscriptionOptions } from './use-virtual-viewport-range';\n","import { useMemo, useSyncExternalStore, type RefObject } from 'react';\nimport { getVirtualViewportRange, type Interval, type VirtualViewportOptions } from '../index';\n\nexport interface VirtualViewportSubscriptionOptions extends Omit<VirtualViewportOptions, 'offset'> {\n  offsetRef?: RefObject<number | null>;\n  subscribe: (listener: () => void) => () => void;\n}\n\nfunction createViewportSnapshotReader({\n  offsetRef,\n  ...options\n}: Omit<VirtualViewportSubscriptionOptions, 'subscribe'>): () => Interval | null {\n  let snapshot: Interval | null = null;\n\n  return () => {\n    const next = getVirtualViewportRange({ ...options, offset: offsetRef?.current ?? 0 });\n\n    // useSyncExternalStore는 같은 범위의 스크롤 신호에 동일한 객체를 반환해야 렌더링을 건너뛴다.\n    if (snapshot?.start !== next?.start || snapshot?.end !== next?.end) {\n      snapshot = next;\n    }\n    return snapshot;\n  };\n}\n\nexport function useVirtualViewportRange({\n  offsetRef,\n  subscribe,\n  viewportSize,\n  contentSize,\n  chunkSize,\n  overscanChunks = 0,\n  padding = 0,\n}: VirtualViewportSubscriptionOptions): Interval | null {\n  const getSnapshot = useMemo(\n    () => createViewportSnapshotReader({ offsetRef, viewportSize, contentSize, chunkSize, overscanChunks, padding }),\n    [offsetRef, viewportSize, contentSize, chunkSize, overscanChunks, padding],\n  );\n\n  return useSyncExternalStore(subscribe, getSnapshot);\n}\n","import type { Interval } from './interval-index';\n\nexport interface VirtualViewportOptions {\n  offset: number;\n  viewportSize: number;\n  contentSize: number;\n  chunkSize: number;\n  overscanChunks?: number;\n  padding?: number;\n}\n\n/** 같은 청크 안에서는 조회 범위를 유지해 작은 스크롤마다 항목을 다시 조회하지 않는다. */\nexport function getVirtualViewportRange({\n  offset,\n  viewportSize,\n  contentSize,\n  chunkSize,\n  overscanChunks = 0,\n  padding = 0,\n}: VirtualViewportOptions): Interval | null {\n  if (\n    ![offset, viewportSize, contentSize, chunkSize, overscanChunks, padding].every(Number.isFinite) ||\n    viewportSize <= 0 ||\n    contentSize <= 0 ||\n    chunkSize <= 0 ||\n    overscanChunks < 0 ||\n    padding < 0\n  ) {\n    return null;\n  }\n\n  const clampedOffset = Math.max(0, Math.min(offset, contentSize - viewportSize));\n  const overscan = Math.floor(overscanChunks);\n  const firstChunk = Math.max(0, Math.floor(clampedOffset / chunkSize) - overscan);\n  const endChunk = Math.ceil((clampedOffset + viewportSize) / chunkSize) + overscan;\n\n  return {\n    start: Math.max(0, firstChunk * chunkSize - padding),\n    end: Math.min(contentSize, endChunk * chunkSize + padding),\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACAA,mBAA8D;;;ACYvD,SAAS,wBAAwB;AAAA,EACtC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA,iBAAiB;AAAA,EACjB,UAAU;AACZ,GAA4C;AAC1C,MACE,CAAC,CAAC,QAAQ,cAAc,aAAa,WAAW,gBAAgB,OAAO,EAAE,MAAM,OAAO,QAAQ,KAC9F,gBAAgB,KAChB,eAAe,KACf,aAAa,KACb,iBAAiB,KACjB,UAAU,GACV;AACA,WAAO;AAAA,EACT;AAEA,QAAM,gBAAgB,KAAK,IAAI,GAAG,KAAK,IAAI,QAAQ,cAAc,YAAY,CAAC;AAC9E,QAAM,WAAW,KAAK,MAAM,cAAc;AAC1C,QAAM,aAAa,KAAK,IAAI,GAAG,KAAK,MAAM,gBAAgB,SAAS,IAAI,QAAQ;AAC/E,QAAM,WAAW,KAAK,MAAM,gBAAgB,gBAAgB,SAAS,IAAI;AAEzE,SAAO;AAAA,IACL,OAAO,KAAK,IAAI,GAAG,aAAa,YAAY,OAAO;AAAA,IACnD,KAAK,KAAK,IAAI,aAAa,WAAW,YAAY,OAAO;AAAA,EAC3D;AACF;;;ADhCA,SAAS,6BAA6B;AAAA,EACpC;AAAA,EACA,GAAG;AACL,GAAiF;AAC/E,MAAI,WAA4B;AAEhC,SAAO,MAAM;AACX,UAAM,OAAO,wBAAwB,EAAE,GAAG,SAAS,QAAQ,WAAW,WAAW,EAAE,CAAC;AAGpF,QAAI,UAAU,UAAU,MAAM,SAAS,UAAU,QAAQ,MAAM,KAAK;AAClE,iBAAW;AAAA,IACb;AACA,WAAO;AAAA,EACT;AACF;AAEO,SAAS,wBAAwB;AAAA,EACtC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA,iBAAiB;AAAA,EACjB,UAAU;AACZ,GAAwD;AACtD,QAAM,kBAAc;AAAA,IAClB,MAAM,6BAA6B,EAAE,WAAW,cAAc,aAAa,WAAW,gBAAgB,QAAQ,CAAC;AAAA,IAC/G,CAAC,WAAW,cAAc,aAAa,WAAW,gBAAgB,OAAO;AAAA,EAC3E;AAEA,aAAO,mCAAqB,WAAW,WAAW;AACpD;","names":[]}

package/dist/react/index.d.cts

@@ -0,0 +1,10 @@
+import { RefObject } from 'react';
+import { VirtualViewportOptions, Interval } from '../index.cjs';
+
+interface VirtualViewportSubscriptionOptions extends Omit<VirtualViewportOptions, 'offset'> {
+    offsetRef?: RefObject<number | null>;
+    subscribe: (listener: () => void) => () => void;
+}
+declare function useVirtualViewportRange({ offsetRef, subscribe, viewportSize, contentSize, chunkSize, overscanChunks, padding, }: VirtualViewportSubscriptionOptions): Interval | null;
+
+export { type VirtualViewportSubscriptionOptions, useVirtualViewportRange };

package/dist/react/index.d.ts

@@ -0,0 +1,10 @@
+import { RefObject } from 'react';
+import { VirtualViewportOptions, Interval } from '../index.js';
+
+interface VirtualViewportSubscriptionOptions extends Omit<VirtualViewportOptions, 'offset'> {
+    offsetRef?: RefObject<number | null>;
+    subscribe: (listener: () => void) => () => void;
+}
+declare function useVirtualViewportRange({ offsetRef, subscribe, viewportSize, contentSize, chunkSize, overscanChunks, padding, }: VirtualViewportSubscriptionOptions): Interval | null;
+
+export { type VirtualViewportSubscriptionOptions, useVirtualViewportRange };

package/dist/react/index.js

@@ -0,0 +1,58 @@
+// src/react/use-virtual-viewport-range.ts
+import { useMemo, useSyncExternalStore } from "react";
+
+// src/viewport-range.ts
+function getVirtualViewportRange({
+  offset,
+  viewportSize,
+  contentSize,
+  chunkSize,
+  overscanChunks = 0,
+  padding = 0
+}) {
+  if (![offset, viewportSize, contentSize, chunkSize, overscanChunks, padding].every(Number.isFinite) || viewportSize <= 0 || contentSize <= 0 || chunkSize <= 0 || overscanChunks < 0 || padding < 0) {
+    return null;
+  }
+  const clampedOffset = Math.max(0, Math.min(offset, contentSize - viewportSize));
+  const overscan = Math.floor(overscanChunks);
+  const firstChunk = Math.max(0, Math.floor(clampedOffset / chunkSize) - overscan);
+  const endChunk = Math.ceil((clampedOffset + viewportSize) / chunkSize) + overscan;
+  return {
+    start: Math.max(0, firstChunk * chunkSize - padding),
+    end: Math.min(contentSize, endChunk * chunkSize + padding)
+  };
+}
+
+// src/react/use-virtual-viewport-range.ts
+function createViewportSnapshotReader({
+  offsetRef,
+  ...options
+}) {
+  let snapshot = null;
+  return () => {
+    const next = getVirtualViewportRange({ ...options, offset: offsetRef?.current ?? 0 });
+    if (snapshot?.start !== next?.start || snapshot?.end !== next?.end) {
+      snapshot = next;
+    }
+    return snapshot;
+  };
+}
+function useVirtualViewportRange({
+  offsetRef,
+  subscribe,
+  viewportSize,
+  contentSize,
+  chunkSize,
+  overscanChunks = 0,
+  padding = 0
+}) {
+  const getSnapshot = useMemo(
+    () => createViewportSnapshotReader({ offsetRef, viewportSize, contentSize, chunkSize, overscanChunks, padding }),
+    [offsetRef, viewportSize, contentSize, chunkSize, overscanChunks, padding]
+  );
+  return useSyncExternalStore(subscribe, getSnapshot);
+}
+export {
+  useVirtualViewportRange
+};
+//# sourceMappingURL=index.js.map

package/dist/react/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/react/use-virtual-viewport-range.ts","../../src/viewport-range.ts"],"sourcesContent":["import { useMemo, useSyncExternalStore, type RefObject } from 'react';\nimport { getVirtualViewportRange, type Interval, type VirtualViewportOptions } from '../index';\n\nexport interface VirtualViewportSubscriptionOptions extends Omit<VirtualViewportOptions, 'offset'> {\n  offsetRef?: RefObject<number | null>;\n  subscribe: (listener: () => void) => () => void;\n}\n\nfunction createViewportSnapshotReader({\n  offsetRef,\n  ...options\n}: Omit<VirtualViewportSubscriptionOptions, 'subscribe'>): () => Interval | null {\n  let snapshot: Interval | null = null;\n\n  return () => {\n    const next = getVirtualViewportRange({ ...options, offset: offsetRef?.current ?? 0 });\n\n    // useSyncExternalStore는 같은 범위의 스크롤 신호에 동일한 객체를 반환해야 렌더링을 건너뛴다.\n    if (snapshot?.start !== next?.start || snapshot?.end !== next?.end) {\n      snapshot = next;\n    }\n    return snapshot;\n  };\n}\n\nexport function useVirtualViewportRange({\n  offsetRef,\n  subscribe,\n  viewportSize,\n  contentSize,\n  chunkSize,\n  overscanChunks = 0,\n  padding = 0,\n}: VirtualViewportSubscriptionOptions): Interval | null {\n  const getSnapshot = useMemo(\n    () => createViewportSnapshotReader({ offsetRef, viewportSize, contentSize, chunkSize, overscanChunks, padding }),\n    [offsetRef, viewportSize, contentSize, chunkSize, overscanChunks, padding],\n  );\n\n  return useSyncExternalStore(subscribe, getSnapshot);\n}\n","import type { Interval } from './interval-index';\n\nexport interface VirtualViewportOptions {\n  offset: number;\n  viewportSize: number;\n  contentSize: number;\n  chunkSize: number;\n  overscanChunks?: number;\n  padding?: number;\n}\n\n/** 같은 청크 안에서는 조회 범위를 유지해 작은 스크롤마다 항목을 다시 조회하지 않는다. */\nexport function getVirtualViewportRange({\n  offset,\n  viewportSize,\n  contentSize,\n  chunkSize,\n  overscanChunks = 0,\n  padding = 0,\n}: VirtualViewportOptions): Interval | null {\n  if (\n    ![offset, viewportSize, contentSize, chunkSize, overscanChunks, padding].every(Number.isFinite) ||\n    viewportSize <= 0 ||\n    contentSize <= 0 ||\n    chunkSize <= 0 ||\n    overscanChunks < 0 ||\n    padding < 0\n  ) {\n    return null;\n  }\n\n  const clampedOffset = Math.max(0, Math.min(offset, contentSize - viewportSize));\n  const overscan = Math.floor(overscanChunks);\n  const firstChunk = Math.max(0, Math.floor(clampedOffset / chunkSize) - overscan);\n  const endChunk = Math.ceil((clampedOffset + viewportSize) / chunkSize) + overscan;\n\n  return {\n    start: Math.max(0, firstChunk * chunkSize - padding),\n    end: Math.min(contentSize, endChunk * chunkSize + padding),\n  };\n}\n"],"mappings":";AAAA,SAAS,SAAS,4BAA4C;;;ACYvD,SAAS,wBAAwB;AAAA,EACtC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA,iBAAiB;AAAA,EACjB,UAAU;AACZ,GAA4C;AAC1C,MACE,CAAC,CAAC,QAAQ,cAAc,aAAa,WAAW,gBAAgB,OAAO,EAAE,MAAM,OAAO,QAAQ,KAC9F,gBAAgB,KAChB,eAAe,KACf,aAAa,KACb,iBAAiB,KACjB,UAAU,GACV;AACA,WAAO;AAAA,EACT;AAEA,QAAM,gBAAgB,KAAK,IAAI,GAAG,KAAK,IAAI,QAAQ,cAAc,YAAY,CAAC;AAC9E,QAAM,WAAW,KAAK,MAAM,cAAc;AAC1C,QAAM,aAAa,KAAK,IAAI,GAAG,KAAK,MAAM,gBAAgB,SAAS,IAAI,QAAQ;AAC/E,QAAM,WAAW,KAAK,MAAM,gBAAgB,gBAAgB,SAAS,IAAI;AAEzE,SAAO;AAAA,IACL,OAAO,KAAK,IAAI,GAAG,aAAa,YAAY,OAAO;AAAA,IACnD,KAAK,KAAK,IAAI,aAAa,WAAW,YAAY,OAAO;AAAA,EAC3D;AACF;;;ADhCA,SAAS,6BAA6B;AAAA,EACpC;AAAA,EACA,GAAG;AACL,GAAiF;AAC/E,MAAI,WAA4B;AAEhC,SAAO,MAAM;AACX,UAAM,OAAO,wBAAwB,EAAE,GAAG,SAAS,QAAQ,WAAW,WAAW,EAAE,CAAC;AAGpF,QAAI,UAAU,UAAU,MAAM,SAAS,UAAU,QAAQ,MAAM,KAAK;AAClE,iBAAW;AAAA,IACb;AACA,WAAO;AAAA,EACT;AACF;AAEO,SAAS,wBAAwB;AAAA,EACtC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA,iBAAiB;AAAA,EACjB,UAAU;AACZ,GAAwD;AACtD,QAAM,cAAc;AAAA,IAClB,MAAM,6BAA6B,EAAE,WAAW,cAAc,aAAa,WAAW,gBAAgB,QAAQ,CAAC;AAAA,IAC/G,CAAC,WAAW,cAAc,aAAa,WAAW,gBAAgB,OAAO;AAAA,EAC3E;AAEA,SAAO,qBAAqB,WAAW,WAAW;AACpD;","names":[]}

package/package.json

@@ -1,6 +1,96 @@
 {
   "name": "@hurraey/interval-virtualizer",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "숫자 구간의 겹침 조회와 청크 기반 화면 범위 계산을 제공하는 TypeScript 라이브러리",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./react": {
+      "import": {
+        "types": "./dist/react/index.d.ts",
+        "default": "./dist/react/index.js"
+      },
+      "require": {
+        "types": "./dist/react/index.d.cts",
+        "default": "./dist/react/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:package": "node scripts/verify-package.mjs",
+    "typecheck": "tsc --noEmit",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "check": "npm run format:check && npm run typecheck && npm test && npm run build && npm run test:package",
+    "prepublishOnly": "npm run check"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "peerDependencies": {
+    "react": "^18.2.0 || ^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "author": {
+    "name": "HURRAEY"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/HURRAEY/interval-virtualizer.git"
+  },
+  "homepage": "https://github.com/HURRAEY/interval-virtualizer#readme",
+  "bugs": {
+    "url": "https://github.com/HURRAEY/interval-virtualizer/issues"
+  },
+  "keywords": [
+    "virtualization",
+    "virtual-scroll",
+    "interval",
+    "segment-tree",
+    "timeline",
+    "typescript",
+    "react"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "@testing-library/react": "16.3.0",
+    "@types/react": "^19.2.3",
+    "@types/react-dom": "^19.2.3",
+    "jsdom": "26.1.0",
+    "prettier": "3.8.3",
+    "react": "19.2.0",
+    "react-dom": "19.2.0",
+    "tsup": "8.5.1",
+    "typescript": "5.9.3",
+    "vitest": "3.2.6"
+  }
+}