@aiquants/virtualscroll 1.18.0 → 1.18.3

package/dist/{src/logger.d.ts → logger.d.cts}

@@ -29,7 +29,18 @@ export interface ILogger {
 /**
  * @class Logger
  * @description A wrapper class for handling logging with levels and prefixes.
+ *
+ * Lazy-argument contract: any function passed as a log argument is treated as a
+ * lazy-evaluation thunk and is invoked (with no arguments) only when the level
+ * is enabled. To log a function itself as a value, wrap it as `() => fn`.
+ * If invoking the thunk throws (e.g. a class constructor or a failing thunk),
+ * the original function value is logged as-is instead of crashing the caller.
  * @description レベルとプレフィックスを使用したログ記録を処理するためのラッパークラス。
+ *
+ * 遅延評価の契約: ログ引数に渡された関数は遅延評価 thunk とみなし、レベルが有効な場合のみ
+ * 引数なしで呼び出す。関数そのものを値としてログしたい場合は `() => fn` とラップすること。
+ * thunk の呼び出しが throw した場合 (class や失敗する thunk) は、呼び出し元をクラッシュ
+ * させずに元の関数値をそのまま出力する仕様。
  */
 export declare class Logger implements ILogger {
     private level;
@@ -85,6 +96,43 @@ export declare class Logger implements ILogger {
      * @param {string} prefix - The new prefix.
      */
     setPrefix(prefix: string): void;
+    /**
+     * @method isEnabled
+     * @description Returns whether the given level would be emitted at the current level (static instance).
+     * @description 指定したレベルが現在のログレベルで出力されるかどうかを返します(静的インスタンス)。
+     * @param {LogLevel} level - The level to query. / 問い合わせるレベル。
+     * @returns {boolean} True if a message at `level` would be emitted. / `level` のメッセージが出力されるなら true。
+     */
+    static isEnabled(level: LogLevel): boolean;
+    /**
+     * @method isEnabled
+     * @description Returns whether the given level would be emitted at the current level.
+     * @description 指定したレベルが現在のログレベルで出力されるかどうかを返します。
+     *
+     * ホットパスで呼び出し側が引数(オブジェクト生成・DOM 読み取り等)を組み立てる前に
+     * ガードするために使う。抑制時は引数評価を丸ごと省ける。
+     *
+     * @param {LogLevel} level - The level to query. / 問い合わせるレベル。
+     * @returns {boolean} True if a message at `level` would be emitted. / `level` のメッセージが出力されるなら true。
+     */
+    isEnabled(level: LogLevel): boolean;
+    /**
+     * Resolves a possibly-lazy log argument.
+     * If the argument is a function it is treated as a thunk and invoked only when the
+     * level is enabled; if the invocation throws (class constructors cannot be called
+     * without `new`, or the thunk itself fails), the original function value is
+     * returned as-is so the log call never crashes the caller and still emits something.
+     * To log a function as a value, wrap it as `() => fn`.
+     * 遅延評価される可能性のあるログ引数を解決する処理。
+     *
+     * 関数が渡された場合はサンク (thunk) とみなし、レベルが有効なとき「だけ」呼び出す。
+     * これにより呼び出し側は `logger.debug(() => ({ ...expensive }))` のように書け、
+     * レベル抑制時にはオブジェクト生成や DOM 読み取りを回避できる。
+     * 呼び出しが throw した場合 (class は `new` なしで呼べず TypeError、または thunk 自体の失敗) は、
+     * ログ呼び出しが呼び出し元をクラッシュさせないよう元の関数値をそのまま返す (握り潰さず出力は残る)。
+     * 関数を値としてログしたい場合は `() => fn` とラップする。非関数値はそのまま素通しするため後方互換。
+     */
+    private static resolveLazy;
     private formatMessage;
     static debug(message?: unknown, ...optionalParams: unknown[]): void;
     debug(message?: unknown, ...optionalParams: unknown[]): void;
@@ -95,4 +143,3 @@ export declare class Logger implements ILogger {
     static error(message?: unknown, ...optionalParams: unknown[]): void;
     error(message?: unknown, ...optionalParams: unknown[]): void;
 }
-//# sourceMappingURL=logger.d.ts.map

package/dist/logger.d.ts

@@ -0,0 +1,146 @@
+/**
+ * @module utils/logger
+ * @description Logger utility for consistent log management across the library.
+ * @description ライブラリ全体で一貫したログ管理を行うためのロガーユーティリティ。
+ */
+/**
+ * @enum LogLevel
+ * @description Log levels for filtering output.
+ * @description 出力をフィルタリングするためのログレベル。
+ */
+export declare enum LogLevel {
+    DEBUG = 0,
+    INFO = 1,
+    WARN = 2,
+    ERROR = 3,
+    NONE = 4
+}
+/**
+ * @interface ILogger
+ * @description Interface for a logger object compatible with Console.
+ * @description Console と互換性のあるロガーオブジェクトのインターフェース。
+ */
+export interface ILogger {
+    debug(message?: unknown, ...optionalParams: unknown[]): void;
+    info(message?: unknown, ...optionalParams: unknown[]): void;
+    warn(message?: unknown, ...optionalParams: unknown[]): void;
+    error(message?: unknown, ...optionalParams: unknown[]): void;
+}
+/**
+ * @class Logger
+ * @description A wrapper class for handling logging with levels and prefixes.
+ *
+ * Lazy-argument contract: any function passed as a log argument is treated as a
+ * lazy-evaluation thunk and is invoked (with no arguments) only when the level
+ * is enabled. To log a function itself as a value, wrap it as `() => fn`.
+ * If invoking the thunk throws (e.g. a class constructor or a failing thunk),
+ * the original function value is logged as-is instead of crashing the caller.
+ * @description レベルとプレフィックスを使用したログ記録を処理するためのラッパークラス。
+ *
+ * 遅延評価の契約: ログ引数に渡された関数は遅延評価 thunk とみなし、レベルが有効な場合のみ
+ * 引数なしで呼び出す。関数そのものを値としてログしたい場合は `() => fn` とラップすること。
+ * thunk の呼び出しが throw した場合 (class や失敗する thunk) は、呼び出し元をクラッシュ
+ * させずに元の関数値をそのまま出力する仕様。
+ */
+export declare class Logger implements ILogger {
+    private level;
+    private prefix;
+    private impl;
+    /**
+     * @constructor
+     * @param {LogLevel} [level=LogLevel.WARN] - The minimum log level to output.
+     * @param {string} [prefix="[virtualscroll]"] - The prefix to add to all log messages.
+     * @param {ILogger} [impl=console] - The implementation to use for logging.
+     */
+    constructor(level?: LogLevel, prefix?: string, impl?: ILogger);
+    private static instance;
+    /**
+     * @method setLevel
+     * @description Updates the current log level for the static instance.
+     * @description 静的インスタンスの現在のログレベルを更新します。
+     * @param {LogLevel} level - The new log level.
+     */
+    static setLevel(level: LogLevel): void;
+    /**
+     * @method setLevel
+     * @description Updates the current log level.
+     * @description 現在のログレベルを更新します。
+     * @param {LogLevel} level - The new log level.
+     */
+    setLevel(level: LogLevel): void;
+    /**
+     * @method setImplementation
+     * @description Updates the logger implementation for the static instance.
+     * @description 静的インスタンスのロガーの実装を更新します。
+     * @param {ILogger} impl - The new logger implementation.
+     */
+    static setImplementation(impl: ILogger): void;
+    /**
+     * @method setImplementation
+     * @description Updates the logger implementation.
+     * @description ロガーの実装を更新します。
+     * @param {ILogger} impl - The new logger implementation.
+     */
+    setImplementation(impl: ILogger): void;
+    /**
+     * @method setPrefix
+     * @description Updates the log prefix for the static instance.
+     * @description 静的インスタンスのログのプレフィックスを更新します。
+     * @param {string} prefix - The new prefix.
+     */
+    static setPrefix(prefix: string): void;
+    /**
+     * @method setPrefix
+     * @description Updates the log prefix.
+     * @description ログのプレフィックスを更新します。
+     * @param {string} prefix - The new prefix.
+     */
+    setPrefix(prefix: string): void;
+    /**
+     * @method isEnabled
+     * @description Returns whether the given level would be emitted at the current level (static instance).
+     * @description 指定したレベルが現在のログレベルで出力されるかどうかを返します(静的インスタンス)。
+     * @param {LogLevel} level - The level to query. / 問い合わせるレベル。
+     * @returns {boolean} True if a message at `level` would be emitted. / `level` のメッセージが出力されるなら true。
+     */
+    static isEnabled(level: LogLevel): boolean;
+    /**
+     * @method isEnabled
+     * @description Returns whether the given level would be emitted at the current level.
+     * @description 指定したレベルが現在のログレベルで出力されるかどうかを返します。
+     *
+     * ホットパスで呼び出し側が引数(オブジェクト生成・DOM 読み取り等)を組み立てる前に
+     * ガードするために使う。抑制時は引数評価を丸ごと省ける。
+     *
+     * @param {LogLevel} level - The level to query. / 問い合わせるレベル。
+     * @returns {boolean} True if a message at `level` would be emitted. / `level` のメッセージが出力されるなら true。
+     */
+    isEnabled(level: LogLevel): boolean;
+    /**
+     * Resolves a possibly-lazy log argument.
+     * If the argument is a function it is treated as a thunk and invoked only when the
+     * level is enabled; if the invocation throws (class constructors cannot be called
+     * without `new`, or the thunk itself fails), the original function value is
+     * returned as-is so the log call never crashes the caller and still emits something.
+     * To log a function as a value, wrap it as `() => fn`.
+     * 遅延評価される可能性のあるログ引数を解決する処理。
+     *
+     * 関数が渡された場合はサンク (thunk) とみなし、レベルが有効なとき「だけ」呼び出す。
+     * これにより呼び出し側は `logger.debug(() => ({ ...expensive }))` のように書け、
+     * レベル抑制時にはオブジェクト生成や DOM 読み取りを回避できる。
+     * 呼び出しが throw した場合 (class は `new` なしで呼べず TypeError、または thunk 自体の失敗) は、
+     * ログ呼び出しが呼び出し元をクラッシュさせないよう元の関数値をそのまま返す (握り潰さず出力は残る)。
+     * 関数を値としてログしたい場合は `() => fn` とラップする。非関数値はそのまま素通しするため後方互換。
+     */
+    private static resolveLazy;
+    private formatMessage;
+    static debug(message?: unknown, ...optionalParams: unknown[]): void;
+    debug(message?: unknown, ...optionalParams: unknown[]): void;
+    static info(message?: unknown, ...optionalParams: unknown[]): void;
+    info(message?: unknown, ...optionalParams: unknown[]): void;
+    static warn(message?: unknown, ...optionalParams: unknown[]): void;
+    warn(message?: unknown, ...optionalParams: unknown[]): void;
+    static error(message?: unknown, ...optionalParams: unknown[]): void;
+    error(message?: unknown, ...optionalParams: unknown[]): void;
+}
+//# sourceMappingURL=logger.d.ts.map

package/dist/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;GAIG;AACH,oBAAY,QAAQ;IAChB,KAAK,IAAI;IACT,IAAI,IAAI;IACR,IAAI,IAAI;IACR,KAAK,IAAI;IACT,IAAI,IAAI;CACX;AAED;;;;GAIG;AACH,MAAM,WAAW,OAAO;IACpB,KAAK,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,GAAG,cAAc,EAAE,OAAO,EAAE,GAAG,IAAI,CAAA;IAC5D,IAAI,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,GAAG,cAAc,EAAE,OAAO,EAAE,GAAG,IAAI,CAAA;IAC3D,IAAI,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,GAAG,cAAc,EAAE,OAAO,EAAE,GAAG,IAAI,CAAA;IAC3D,KAAK,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,GAAG,cAAc,EAAE,OAAO,EAAE,GAAG,IAAI,CAAA;CAC/D;AAED;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,MAAO,YAAW,OAAO;IAClC,OAAO,CAAC,KAAK,CAAU;IACvB,OAAO,CAAC,MAAM,CAAQ;IACtB,OAAO,CAAC,IAAI,CAAS;IAErB;;;;;OAKG;gBACS,KAAK,GAAE,QAAwB,EAAE,MAAM,GAAE,MAA0B,EAAE,IAAI,GAAE,OAAiB;IAMxG,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAuD;IAE9E;;;;;OAKG;IACH,MAAM,CAAC,QAAQ,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI;IAItC;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI;IAI/B;;;;;OAKG;IACH,MAAM,CAAC,iBAAiB,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI;IAI7C;;;;;OAKG;IACH,iBAAiB,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI;IAItC;;;;;OAKG;IACH,MAAM,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAItC;;;;;OAKG;IACH,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAI/B;;;;;;OAMG;IACH,MAAM,CAAC,SAAS,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO;IAI1C;;;;;;;;;;OAUG;IACH,SAAS,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO;IAInC;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,MAAM,CAAC,WAAW;IAc1B,OAAO,CAAC,aAAa;IAOrB,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,GAAG,cAAc,EAAE,OAAO,EAAE,GAAG,IAAI;IAInE,KAAK,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,GAAG,cAAc,EAAE,OAAO,EAAE,GAAG,IAAI;IAM5D,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,GAAG,cAAc,EAAE,OAAO,EAAE,GAAG,IAAI;IAIlE,IAAI,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,GAAG,cAAc,EAAE,OAAO,EAAE,GAAG,IAAI;IAM3D,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,GAAG,cAAc,EAAE,OAAO,EAAE,GAAG,IAAI;IAIlE,IAAI,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,GAAG,cAAc,EAAE,OAAO,EAAE,GAAG,IAAI;IAM3D,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,GAAG,cAAc,EAAE,OAAO,EAAE,GAAG,IAAI;IAInE,KAAK,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,GAAG,cAAc,EAAE,OAAO,EAAE,GAAG,IAAI;CAK/D"}

package/dist/tapScrollCircleSampleVisual.d.cts

@@ -0,0 +1,2 @@
+import { TapScrollCircleProps } from './TapScrollCircle.cjs';
+export declare const tapScrollCircleSampleVisual: NonNullable<TapScrollCircleProps["renderVisual"]>;

package/dist/tapScrollCircleSampleVisual.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tapScrollCircleSampleVisual.d.ts","sourceRoot":"","sources":["../src/tapScrollCircleSampleVisual.tsx"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAA8B,MAAM,uBAAuB,CAAA;AAI7F,eAAO,MAAM,2BAA2B,EAAE,WAAW,CAAC,oBAAoB,CAAC,cAAc,CAAC,CAgEzF,CAAA"}

package/dist/{src/useFenwickMapTree.d.ts → useFenwickMapTree.d.cts}

@@ -26,6 +26,20 @@ type ValueUpdate = {
  * @classdesc Fenwick Tree (バイナリインデックスツリー) の実装。
  * このデータ構造は、接頭辞和の計算と更新を対数時間で効率的に実行。
  * 可変サイズのアイテムのオフセットを管理できるため、特に仮想スクロールで有用。
+ *
+ * @remarks Memory: exact offsets are the design priority, so every materialized/updated row keeps
+ * an entry in `tree` and `deltas`. Memory therefore grows with the number of materialized elements,
+ * not with `size`. Rows equal to `baseValue` are pruned (zero-delta), but there is no eviction of
+ * measured deltas — evicting one would silently snap that row back to the estimated `baseValue` and
+ * corrupt `total`, which is incompatible with the exact-offset guarantee. If a hard memory ceiling
+ * is required, discard off-screen measured heights in the consumer layer (e.g. an LRU height cache)
+ * and let those rows fall back to the estimate there, rather than inside this tree.
+ * @remarks メモリ: 厳密オフセットを設計上の最優先とするため、具現化/更新された行はすべて `tree` と
+ * `deltas` にエントリを保持する。よってメモリは `size` ではなく具現化済み要素数に比例して増える。
+ * `baseValue` と一致する行は zero-delta 枝刈りされるが、計測済み delta の evict は行わない。evict すると
+ * その行が黙って推定値 `baseValue` へ戻り `total` が破損し、厳密オフセット保証と両立しないためである。
+ * ハードなメモリ上限が必要な場合は、この木の内部ではなく消費側 (LRU 高さキャッシュ等) で可視域外の
+ * 実測値を破棄し、そこで既定推定へ委ねる設計とすること。
  */
 export declare class FenwickMapTree {
     /**
@@ -76,8 +90,15 @@ export declare class FenwickMapTree {
     });
     /**
      * @method reset
-     * @description Resets the Fenwick Tree with a new size and initial values.
-     * @description Fenwick Tree を新しいサイズと初期値でリセット。
+     * @description Resets the Fenwick Tree with a new size and initial values. The size is
+     * normalized on entry (non-finite/negative sizes collapse to 0, fractions are truncated).
+     * When `valueOrFn` is a function, all sampling/materialization values are computed and
+     * validated (finite-only) before the tree state is mutated, so a `valueFn` returning
+     * NaN/Infinity throws while leaving the previous tree state intact instead of a half-built one.
+     * @description Fenwick Tree を新しいサイズと初期値でリセット。size は入口で正規化する
+     * (非有限/負は 0 に縮退、小数は切り捨て)。`valueOrFn` が関数の場合、サンプリング/具現化の値は
+     * 木の状態を変異させる前に計算・検証 (有限数のみ) するため、NaN/Infinity を返す `valueFn` は
+     * throw しつつ木を半構築で残さず直前の状態を無傷に保つ方針。
      * @param {number} size - The total number of items.
      * @param {number | ((index: number) => number)} valueOrFn - The value for all elements, or a function to generate values.
      * @param {{ sampleRange?: { from: number; to: number }, materialize?: boolean }} [options] - Optional settings for initialization.
@@ -101,14 +122,35 @@ export declare class FenwickMapTree {
     }): void;
     /**
      * @private
-     * @method _calculateMode
-     * @description Calculates the mode (most frequent value) within a given range of values generated by `valueFn`. If multiple modes exist, it returns their average. If no value appears more than once, it returns the median of the range. This approach helps determine a representative `baseValue` for the Fenwick tree, especially for data with high variance. It also returns the array of values generated within the range for reuse.
-     * @description `valueFn` によって生成される値の指定された範囲内の最頻値を計算する。最頻値が複数存在する場合は、それらの平均値を返す。どの値も複数回出現しない場合は、範囲の中央値を返す。このアプローチは、特に分散の大きいデータに対して、Fenwick Tree の代表的な `baseValue` を決定するのに役立つ。また、再利用のために範囲内で生成された値の配列も返す。
+     * @method _collectValidatedValues
+     * @description Evaluates `valueFn` over the inclusive `[from, to]` range and returns the values, throwing on any non-finite result. Validation happens here, before any tree mutation, so a poisoned `valueFn` can never leave the tree half-built.
+     * @description `valueFn` を閉区間 `[from, to]` で評価して値配列を返す。非有限値は throw で拒否。検証を木の変異前 (このメソッド内) で行うことで、汚染された `valueFn` が木を半構築のまま残す事態の防止。
+     * @param {(index: number) => number} valueFn - The value-generating function to evaluate.
      * @param {number} from - The starting index of the range (inclusive).
      * @param {number} to - The ending index of the range (inclusive).
-     * @returns {{ mode: number; materializedValues: number[] }} An object containing the calculated mode and the array of generated values.
+     * @returns {number[]} The validated (finite-only) values in index order.
+     */
+    private static _collectValidatedValues;
+    /**
+     * @private
+     * @method _modeOrMedian
+     * @description Reduces a sample of generated values to a single representative height: the mode when it is frequent enough to be trustworthy, otherwise the median. A value is only accepted as the mode when its frequency exceeds 20% of the sample; this prevents periodic or near-uniform data (where sampling bias can make an arbitrary value momentarily frequent) from picking an unrepresentative base. Multiple co-modes are averaged.
+     * @description サンプル値を 1 つの代表的な高さへ縮約する。信頼できるほど頻出する場合は最頻値を、そうでなければ中央値を返す。最頻値はサンプルの 20% を超える頻度のときのみ採用し、周期的/ほぼ一様なデータ (サンプリング偏りで任意の値が一時的に頻出しうる) が非代表値を選ぶのを防ぐ。同率最頻値が複数ある場合は平均する。
+     * @param {number[]} values - The sampled values (mutated in place by sorting).
+     * @returns {number} The representative base value.
+     */
+    private static _modeOrMedian;
+    /**
+     * @private
+     * @method _sampleBaseValueStrided
+     * @description Estimates `baseValue` by evaluating `valueFn` at up to `sampleCount` points spread across the entire `[0, size-1]` range, then reducing them via `_modeOrMedian`. Spanning the whole list (rather than a fixed head window) makes the majority height win even when the first items are atypical (hero/heading rows). The stride uses `ceil(size / sampleCount)` so the samples always span the whole range — `floor` would collapse to stride 1 for `sampleCount < size < 2 * sampleCount` and only ever look at the head. The stride is also forced odd to avoid aliasing against common even-period layouts (e.g. alternating or 20-row cycles), which a stride that shares a factor with the period would otherwise collapse into a single residue. For a uniform list every sample is identical, so the estimate is unchanged. Non-finite sample values throw before any state is touched.
+     * @description `valueFn` を `[0, size-1]` 全域に散らした最大 `sampleCount` 点で評価し、`_modeOrMedian` で縮約して `baseValue` を推定する。先頭固定ウィンドウではなくリスト全体を跨ぐことで、先頭が非典型 (ヒーロー/見出し行) でも多数派の高さが選ばれる。ストライドは `ceil(size / sampleCount)` を用いて常に全域を跨がせる (`floor` だと `sampleCount < size < 2 * sampleCount` で stride=1 に潰れ先頭しか見ない盲点が生じる)。さらに奇数へ強制し、周期と公約数を持つストライドがサンプルを 1 剰余類へ潰してしまう周期レイアウト (交互・20行周期など) とのエイリアシングを避ける。一様リストでは全サンプルが同一なので推定値は不変。非有限のサンプル値は状態を変異させる前に throw で拒否。
+     * @param {(index: number) => number} valueFn - The value-generating function to sample.
+     * @param {number} size - The total number of items the tree will manage.
+     * @param {number} sampleCount - Maximum number of points to evaluate.
+     * @returns {number} The estimated base value.
      */
-    private _calculateMode;
+    private static _sampleBaseValueStrided;
     /**
      * @method update
      * @description Updates the value at a given index.
@@ -126,16 +168,16 @@ export declare class FenwickMapTree {
     updates(updates: ValueUpdate[]): number | undefined;
     /**
      * @method updateDelta
-     * @description Updates the delta at a given index and propagates the change through the tree.
-     * @description 指定されたインデックスのデルタを更新し、変更をツリーに伝播させる。
+     * @description Updates the delta at a given index and propagates the change through the tree. A change that would make the effective value (`baseValue` + delta) negative is rejected with an error, mirroring the negative-value rejection of `update`/`updates`.
+     * @description 指定されたインデックスのデルタを更新し、変更をツリーに伝播させる。適用後の実効値 (`baseValue` + delta) が負になる変更は `update`/`updates` の負値拒否と対称に throw で拒否する方針。
      * @param {number} index - The 0-based index to update.
      * @param {number} change - The value to add to the delta at the given index.
      */
     updateDelta(index: number, change: number): number | undefined;
     /**
      * @method updateDeltas
-     * @description Updates the deltas at given indices and propagates the changes through the tree.
-     * @description 指定されたインデックスのデルタを更新し、変更をツリーに伝播させる。
+     * @description Updates the deltas at given indices and propagates the changes through the tree. All entries are validated up front (atomicity): out-of-range or non-integer indices, non-finite changes, and changes whose resulting effective value (`baseValue` + delta) would turn negative are rejected with an error before anything is applied. Negative effective values would break the monotonic prefix sums that `_descend`/`_findIndexLarge` rely on.
+     * @description 指定されたインデックスのデルタを更新し、変更をツリーに伝播させる。全件を先に検証してから適用する (アトミック性): 範囲外/非整数の index、非有限の change、適用後の実効値 (`baseValue` + delta) が負になる変更はいずれも適用前に throw で拒否。負の実効値は `_descend`/`_findIndexLarge` が前提とする累積和の単調性を破壊するため。
      * @param {DeltaUpdate[]} updates - An array of updates, each with an index and the change to apply.
      */
     updateDeltas(updates: DeltaUpdate[]): number | undefined;
@@ -168,8 +210,8 @@ export declare class FenwickMapTree {
     /**
      * @private
      * @method _materialize
-     * @description Materializes the value at a specific index if it hasn't been already.
-     * @description 特定のインデックスの値がまだ具現化されていない場合に具現化する。
+     * @description Materializes the value at a specific index if it hasn't been already. A non-finite `valueFn` result throws before any mutation, symmetric with the update-path validation, so the tree is never poisoned.
+     * @description 特定のインデックスの値がまだ具現化されていない場合に具現化する。`valueFn` の非有限な返値は変異前に throw で拒否 (update 系の検証と対称) し、木を汚染させない方針。
      * @param {number} index - The 0-based index to materialize.
      * @param {boolean} [updateTree=true] - Whether to update the Fenwick tree after materialization.
      */
@@ -195,6 +237,16 @@ export declare class FenwickMapTree {
      * @returns {{ index: number; total: number | undefined; cumulative: number | undefined; currentValue: number | undefined; safeIndex: number | undefined }} Binary search result.
      */
     private _findIndex;
+    /**
+     * @private
+     * @method _descend
+     * @description Performs a single bitwise descent over the current tree state, returning the candidate index for the boundary condition without mutating the tree.
+     * @description 現在の木の状態に対してビット降下を 1 回実行し、木を変異させずに境界条件の候補インデックスを返す。
+     * @param {number} target - Target cumulative value.
+     * @param {boolean} chooseLowerBound - When true, finds the smallest index meeting or exceeding the target; otherwise finds the largest index not exceeding it.
+     * @returns {number} The candidate index (may be out of range when no index satisfies the condition).
+     */
+    private _descend;
     /**
      * Executes a binary search using bigint arithmetic for extremely large sizes.
      *
@@ -251,11 +303,59 @@ export declare class FenwickMapTree {
     calculateAccumulatedError(): number;
     /**
      * @method changeSize
-     * @description Changes the size of the Fenwick Tree.
-     * @description Fenwick Tree のサイズを変更する。
+     * @description Changes the size of the Fenwick Tree. Only tail growth/shrink is modelled: this
+     * method receives a size delta, not an index mapping, so it assumes items are appended to or
+     * removed from the tail. Existing rows keep their index-to-height association. It therefore
+     * cannot represent a middle insertion/deletion — after such a structural change the index↔height
+     * mapping is no longer preserved and the tree's deltas would apply to the wrong rows. Consumers
+     * that insert or remove items in the middle must instead reset the tree (see
+     * `useFenwickMapTree`'s `resetOnValueFnChange`, surfaced as `resetOnGetItemHeightChange` in
+     * VirtualScroll) or remount the component with a new `key`.
+     * @description Fenwick Tree のサイズを変更する。モデル化するのは末尾の伸長/縮小のみ: 本メソッドは
+     * サイズ差分のみを受け取りインデックスの対応表は受け取らないため、要素は末尾に追加/末尾から削除
+     * されると仮定する。既存行は index↔高さ の対応を保つ。したがって中間挿入/削除は表現できず、その
+     * ような構造変更の後は index↔高さ の対応が保存されず、木の delta が誤った行へ適用されてしまう。
+     * 中間で要素を挿入/削除する消費側は、代わりに木をリセットするか (`useFenwickMapTree` の
+     * `resetOnValueFnChange`。VirtualScroll では `resetOnGetItemHeightChange` として公開) 、新しい
+     * `key` でコンポーネントを再マウントすること。
+     * @remarks Validation: a non-finite `newSize` (NaN/Infinity) throws because it would poison
+     * `size`/`total` irrecoverably. Fractional sizes are truncated and negative sizes collapse to 0,
+     * matching the normalization rule of `reset`.
+     * @remarks 検証: 非有限の `newSize` (NaN/Infinity) は `size`/`total` を復旧不能に汚染するため
+     * throw。小数は切り捨て、負値は 0 に縮退 (`reset` の正規化規則と同一)。
      * @param {number} newSize - The new size of the tree.
      */
     changeSize(newSize: number): void;
+    /**
+     * @private
+     * @method _minCoveredLowBound
+     * @description Computes `min(t - lowestSetBit(t))` over the newly-activated node range `t in (oldSize, newSize]`. Any delta whose 1-based tree index is at or below this bound cannot be covered by any newly-activated node and can be skipped during an incremental grow.
+     * @description 新規有効化ノード範囲 `t in (oldSize, newSize]` にわたる `min(t - lowestSetBit(t))` を算出する。1 始まりの木インデックスがこの下限以下の delta はどの新規ノードにも覆われないため、増分伸長時にスキップできる。
+     * @param {number} oldSize - The previous size (exclusive lower bound of the new node range).
+     * @param {number} newSize - The new size (inclusive upper bound of the new node range).
+     * @returns {number} The minimum left boundary `t - lowestSetBit(t)` of the newly-activated nodes.
+     */
+    private static _minCoveredLowBound;
+    /**
+     * @private
+     * @method _propagateDeltaToGrownNodes
+     * @description Propagates a single delta into the tree nodes newly activated by a tail growth, i.e. parent-chain nodes in `(oldSize, newSize]`.
+     * @description 末尾伸長で新規有効化されたノード ((oldSize, newSize] にある親チェーンノード) へ単一 delta を伝播する。
+     * @param {number} index - The 0-based delta index.
+     * @param {number} delta - The delta value to propagate.
+     * @param {number} oldSize - The previous size.
+     * @param {number} newSize - The new (larger) size.
+     */
+    private _propagateDeltaToGrownNodes;
+    /**
+     * @private
+     * @method _growSize
+     * @description Extends the tree to a larger size incrementally, propagating existing deltas into newly-activated higher-order tree nodes only. Candidate deltas are narrowed via `_minCoveredLowBound`, so a typical `+1` tail append costs amortized O(log n) instead of O(D log n) (D = number of materialized deltas).
+     * @description ツリーを末尾方向に増分的に拡張する。既存 delta を新たに有効化された上位ノードにのみ伝播する。候補 delta は `_minCoveredLowBound` で絞り込むため、通常の +1 末尾追記は O(D log n) (D = 具現化済み delta 数) ではなく償却 O(log n) で済む。
+     * @param {number} oldSize - The previous size.
+     * @param {number} newSize - The new (larger) size.
+     */
+    private _growSize;
     /**
      * @method getSize
      * @description Gets the size of the tree.
@@ -308,6 +408,29 @@ export declare class FenwickMapTree {
  * @description `FenwickMapTree` インスタンスを作成・管理する React フック。
  * ツリーインスタンスは再レンダリングされても同一性を維持する。`size` または `valueOrFn` が
  * 変更された場合に新しいインスタンスが作成される。
+ *
+ * @remarks Structural changes: `size` changes are treated as tail append/remove (see
+ * `FenwickMapTree.changeSize`). If a `size`/`itemCount` change actually reflects a middle
+ * insertion or deletion, the `valueOrFn` index↔height association is not preserved by an
+ * incremental resize; set `resetOnValueFnChange` to `true` (so the tree fully re-samples on
+ * every `valueOrFn` change) or remount with a new `key` when the list structure changes.
+ * @remarks 構造変更: `size` 変更は末尾追加/削除として扱う (`FenwickMapTree.changeSize` 参照)。
+ * `size`/`itemCount` の変更が実は中間挿入/削除を表す場合、増分リサイズでは `valueOrFn` の
+ * index↔高さ 対応が保存されないため、`resetOnValueFnChange` を `true` にする (毎回の `valueOrFn`
+ * 変更で木を全面再サンプリング) か、リスト構造変更時に新しい `key` で再マウントすること。
+ *
+ * @remarks Render-phase design constraint: this hook applies tree changes synchronously during
+ * render (not in an effect) because VirtualScroll reads `getTotal()` synchronously right after a
+ * size change. A consequence is that React concurrent's discarded renders are not undone — a
+ * shrink (deltas deletion) is irreversible if the render is thrown away. To stay safe, always pass
+ * a memoized `options`/`sampleRange` (e.g. `useMemo`) and a memoized `valueOrFn` (e.g. `useCallback`)
+ * so an unstable reference does not trigger a destructive reset every render.
+ * @remarks render フェーズの設計上の制約: 本フックはツリー変更を effect ではなく render 中に同期的に
+ * 適用する。VirtualScroll がサイズ変更直後に `getTotal()` を同期的に読む契約に依存するためである。
+ * 結果として React concurrent の破棄されたレンダーは巻き戻されず、縮小 (deltas 削除) はレンダーが
+ * 破棄されると不可逆になる。安全のため `options`/`sampleRange` は必ずメモ化して渡し (`useMemo`)、
+ * `valueOrFn` もメモ化する (`useCallback`) こと。不安定な参照は毎レンダーの破壊的 reset を招く。
+ *
  * @param {number} size - The total number of items.
  * @param {number | ((index: number) => number)} valueOrFn - The value for all elements, or a function to generate values.
  * @param {number | ((index: number) => number)} valueOrFn - 全要素の均一な値、または値を生成する関数。不要なツリーの再作成を防ぐため、この関数は `useCallback` でメモ化すること。
@@ -325,4 +448,3 @@ export declare const useFenwickMapTree: (size: number, valueOrFn: number | ((ind
     resetOnValueFnChange?: boolean;
 }) => FenwickMapTree;
 export {};
-//# sourceMappingURL=useFenwickMapTree.d.ts.map