@aiquants/virtualscroll 1.18.5 → 1.19.1

package/src/cli.server.spec.ts

@@ -0,0 +1,137 @@
+/**
+ * Regression tests for the CLI entry point: usage guidance must always be
+ * printed via console (never suppressed by the Logger's default WARN level),
+ * and importing the module must not trigger the CLI.
+ * CLI エントリポイントの回帰テスト。usage 案内が Logger の既定レベル (WARN) に
+ * 抑制されず常時 console 表示されること、および import 時に CLI が起動しないことの検証。
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"
+
+// spawn / existsSync をモックし、実プロセス起動・実ファイル参照なしで CLI 分岐を検証する
+vi.mock("node:child_process", async (importOriginal) => {
+    const actual = await importOriginal<typeof import("node:child_process")>()
+    const spawnMock = vi.fn(() => ({ on: vi.fn() }))
+    return {
+        ...actual,
+        default: { ...actual, spawn: spawnMock },
+        spawn: spawnMock,
+    }
+})
+vi.mock("node:fs", async (importOriginal) => {
+    const actual = await importOriginal<typeof import("node:fs")>()
+    // interop で default 経由の名前解決が行われるため、default 側にも同一モックを載せる
+    const existsSyncMock = vi.fn(() => true)
+    return {
+        ...actual,
+        default: { ...actual, existsSync: existsSyncMock },
+        existsSync: existsSyncMock,
+    }
+})
+
+import { spawn } from "node:child_process"
+import { existsSync } from "node:fs"
+import { runCli } from "./cli.server"
+
+const USAGE_MESSAGE = "Usage: npx @aiquants/virtualscroll demo"
+
+describe("cli.server", () => {
+    let consoleErrorSpy: ReturnType<typeof vi.spyOn>
+    let exitSpy: ReturnType<typeof vi.spyOn>
+
+    beforeEach(() => {
+        // console.error を捕捉して usage 案内の常時表示を検証する
+        consoleErrorSpy = vi.spyOn(console, "error").mockImplementation(() => {})
+        // process.exit は throw に差し替え、以降のコードへ進まない実挙動を再現する
+        exitSpy = vi.spyOn(process, "exit").mockImplementation(((code?: number) => {
+            throw new Error(`process.exit(${code})`)
+        }) as never)
+        vi.mocked(spawn).mockClear()
+        vi.mocked(existsSync).mockClear()
+    })
+
+    afterEach(() => {
+        consoleErrorSpy.mockRestore()
+        exitSpy.mockRestore()
+    })
+
+    it("prints unknown command and usage to console.error and exits 1", () => {
+        // 未知コマンドではコマンド名 + usage が console.error 直で表示される (Logger レベル非依存)
+        expect(() => runCli(["foo"])).toThrow("process.exit(1)")
+        const messages = consoleErrorSpy.mock.calls.map((call) => String(call[0]))
+        expect(messages).toContain("Unknown command: foo")
+        expect(messages).toContain(USAGE_MESSAGE)
+    })
+
+    it("prints usage without 'Unknown command: undefined' when no args are given", () => {
+        // 引数なしでは undefined を埋め込んだ Unknown command 行を出さず usage のみ表示する
+        expect(() => runCli([])).toThrow("process.exit(1)")
+        const messages = consoleErrorSpy.mock.calls.map((call) => String(call[0]))
+        expect(messages).toContain(USAGE_MESSAGE)
+        expect(messages.some((message) => message.includes("Unknown command"))).toBe(false)
+    })
+
+    it("prints source-checkout guidance via console.error and exits 1 when demo dir is missing", () => {
+        // demo ディレクトリ不在 (published tarball 相当) では案内を常時表示して exit 1 する
+        vi.mocked(existsSync).mockReturnValue(false)
+        expect(() => runCli(["demo"])).toThrow("process.exit(1)")
+        const messages = consoleErrorSpy.mock.calls.map((call) => String(call[0]))
+        expect(messages.some((message) => message.includes("only available in a source checkout"))).toBe(true)
+        expect(vi.mocked(spawn)).not.toHaveBeenCalled()
+    })
+
+    it("announces startup and spawns the demo server when demo dir exists", () => {
+        // demo ディレクトリが存在する場合は起動メッセージを常時表示し pnpm run dev を spawn する
+        vi.mocked(existsSync).mockReturnValue(true)
+        runCli(["demo"])
+        const messages = consoleErrorSpy.mock.calls.map((call) => String(call[0]))
+        expect(messages).toContain("Starting demo server...")
+        expect(vi.mocked(spawn)).toHaveBeenCalledWith("pnpm", ["run", "dev"], expect.objectContaining({ stdio: "inherit" }))
+        expect(exitSpy).not.toHaveBeenCalled()
+    })
+
+    it("propagates a non-zero child exit code to process.exitCode via the close handler", () => {
+        // 子プロセスが非ゼロ終了したら親の exitCode に伝播する (シェル連結/CI で失敗が成功扱いにならない)
+        const previousExitCode = process.exitCode
+        try {
+            vi.mocked(existsSync).mockReturnValue(true)
+            runCli(["demo"])
+            const onMock = vi.mocked(spawn).mock.results[0]?.value.on as ReturnType<typeof vi.fn>
+            const closeHandler = onMock.mock.calls.find((call) => call[0] === "close")?.[1] as (code: number | null) => void
+            expect(closeHandler).toBeTypeOf("function")
+            closeHandler(3)
+            expect(process.exitCode).toBe(3)
+            // code=null (シグナル終了等) は汎用の 1 にフォールバックする
+            process.exitCode = undefined
+            closeHandler(null)
+            expect(process.exitCode).toBe(1)
+            // 正常終了 (code=0) では exitCode を汚染しない
+            process.exitCode = undefined
+            closeHandler(0)
+            expect(process.exitCode).toBeUndefined()
+        } finally {
+            process.exitCode = previousExitCode
+        }
+    })
+
+    it("sets process.exitCode to 1 when the child emits an error (spawn failure)", () => {
+        // spawn 自体の失敗 (コマンド不在等) も非ゼロ終了として親へ伝播する
+        const previousExitCode = process.exitCode
+        try {
+            vi.mocked(existsSync).mockReturnValue(true)
+            runCli(["demo"])
+            const onMock = vi.mocked(spawn).mock.results[0]?.value.on as ReturnType<typeof vi.fn>
+            const errorHandler = onMock.mock.calls.find((call) => call[0] === "error")?.[1] as (err: Error) => void
+            expect(errorHandler).toBeTypeOf("function")
+            errorHandler(new Error("spawn pnpm ENOENT"))
+            expect(process.exitCode).toBe(1)
+        } finally {
+            process.exitCode = previousExitCode
+        }
+    })
+
+    it("does not run the CLI on import (direct-run guard)", () => {
+        // モジュール import 自体では spawn も exit も発生していない (トップレベルガードの検証)
+        // 上記テスト以外での呼び出しが無いことは各テストの mockClear + アサーションで担保される
+        expect(vi.mocked(spawn)).not.toHaveBeenCalled()
+    })
+})

package/src/cli.server.ts

@@ -0,0 +1,110 @@
+/**
+ * CLI entry point for the @aiquants/virtualscroll package. Handles the
+ * "demo" command that launches the local demo server, and prints usage
+ * guidance for unknown or missing commands.
+ * @aiquants/virtualscroll パッケージの CLI エントリポイント。demo コマンドによる
+ * ローカルデモサーバー起動と、不明・未指定コマンド時の usage 案内の担当。
+ */
+import { spawn } from "node:child_process"
+import { existsSync, realpathSync } from "node:fs"
+import path from "node:path"
+import { fileURLToPath, pathToFileURL } from "node:url"
+import { Logger } from "./logger"
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = path.dirname(__filename)
+
+// usage 案内文。Logger の既定レベル (WARN) では info が抑制されるため、
+// usage/案内は Logger を経由せず console 直で常時表示する。
+const USAGE_MESSAGE = "Usage: npx @aiquants/virtualscroll demo"
+
+/**
+ * Run the virtualscroll CLI with the given arguments: start the demo server
+ * for the "demo" command, otherwise print usage guidance and exit with code 1.
+ * When the demo server exits with a non-zero code or fails to spawn, the
+ * failure is propagated to the parent process via process.exitCode.
+ * 与えられた引数で virtualscroll CLI を実行し、demo コマンドならデモサーバーを
+ * 起動、それ以外は usage 案内を表示して終了コード 1 で終了する処理。デモサーバーが
+ * 非ゼロ終了または起動失敗した場合は process.exitCode で親プロセスへ失敗を伝播。
+ *
+ * @param {string[]} args - Command-line arguments (without the node/script prefix).
+ * @returns {void} Nothing. デモ起動または usage 表示後の終了のみで戻り値なし。
+ */
+export function runCli(args: string[]): void {
+    if (args[0] === "demo") {
+        // The demo directory lives next to the built CLI in a source checkout
+        // (dist/cli.js -> ../demo). It is intentionally NOT part of the published
+        // npm tarball ("files" excludes it), because the demo requires its own
+        // demo/ tree plus a full node_modules install that cannot be shipped.
+        // 公開 tarball には demo/ が含まれないため、ソースチェックアウト以外では
+        // ここで存在確認し、ENOENT でクラッシュさせず明確な案内を出して終了する。
+        const demoPath = path.join(__dirname, "..", "demo")
+
+        if (!existsSync(demoPath)) {
+            // 案内は Logger のレベル設定に左右されないよう console.error 直で表示する
+            console.error(
+                "The 'demo' command is only available in a source checkout of @aiquants/virtualscroll.\n" + "The demo app is not bundled in the published npm package.\n" + "To run it, clone the repository and inside the 'demo/' directory run:\n" + "  pnpm install && pnpm dev",
+            )
+            process.exit(1)
+        }
+
+        // 起動メッセージも Logger.info では既定レベルで抑制されるため console 直で常時表示する
+        // (noConsole の allow 対象かつ stdout を汚さない console.error を使用)
+        console.error("Starting demo server...")
+
+        const child = spawn("pnpm", ["run", "dev"], {
+            cwd: demoPath,
+            stdio: "inherit",
+            shell: process.platform === "win32",
+        })
+
+        child.on("close", (code) => {
+            if (code !== 0) {
+                // 子プロセスの失敗を親 CLI の終了コードへ伝播する (シェル連結や CI で失敗を成功扱いさせない)。
+                // シグナル終了等で code が null の場合は汎用の 1 にフォールバックする
+                Logger.error(`Demo server process exited with code ${code}`)
+                process.exitCode = code ?? 1
+            }
+        })
+
+        child.on("error", (err) => {
+            // spawn 自体の失敗 (コマンド不在等) も非ゼロ終了として親へ伝播する
+            Logger.error("Failed to start demo server:", err)
+            process.exitCode = 1
+        })
+    } else {
+        // 引数なしの場合は "Unknown command: undefined" を出さず usage のみ表示する
+        if (args.length > 0) {
+            console.error(`Unknown command: ${args[0]}`)
+        }
+        console.error(USAGE_MESSAGE)
+        process.exit(1)
+    }
+}
+
+/**
+ * Determine whether this module is the direct execution entry (bin script)
+ * rather than an import from tests or other modules.
+ * このモジュールが (テスト等からの import ではなく) bin スクリプトとして
+ * 直接実行されたエントリかどうかの判定。
+ *
+ * @returns {boolean} True when executed directly as the process entry script. 直接実行時に true。
+ */
+function isDirectRun(): boolean {
+    const entryPath = process.argv[1]
+    if (!entryPath) {
+        return false
+    }
+    try {
+        // npx の bin シンボリックリンク経由でも一致するよう realpath で実体を解決して比較する
+        return pathToFileURL(realpathSync(entryPath)).href === import.meta.url
+    } catch {
+        // エントリパスが解決不能な場合は直接実行とみなさない
+        return false
+    }
+}
+
+// bin として直接実行された場合のみ CLI を起動する (spec からの import 時は起動しない)
+if (isDirectRun()) {
+    runCli(process.argv.slice(2))
+}

package/src/index.ts

@@ -0,0 +1,23 @@
+/**
+ * @aiquants/virtualscroll
+ *
+ * High-performance virtual scrolling component for React with variable item heights.
+ * 可変なアイテム高さに対応したReact用の高性能仮想スクロールコンポーネント。
+ */
+
+export { ScrollBar, type ScrollBarProps, type ScrollBarTapCircleOptions, type ScrollBarThumbOverlayRenderProps } from "./ScrollBar.tsx"
+export { ScrollPane, type ScrollPaneContentInsets, type ScrollPaneHandle, type ScrollPaneInertiaOptions, type ScrollPaneProps } from "./ScrollPane.tsx"
+export type { TapScrollCircleRenderProps } from "./TapScrollCircle.tsx"
+export { tapScrollCircleSampleVisual } from "./tapScrollCircleSampleVisual.tsx"
+export { FenwickMapTree, useFenwickMapTree } from "./useFenwickMapTree.ts"
+export { useHeightCache } from "./useHeightCache.ts"
+export { useLruCache } from "./useLruCache.ts"
+export { minmax } from "./utils.ts"
+export {
+    VirtualScroll,
+    type VirtualScrollBehaviorOptions,
+    type VirtualScrollHandle,
+    type VirtualScrollProps,
+    type VirtualScrollRange,
+    type VirtualScrollScrollBarOptions,
+} from "./VirtualScroll.tsx"

package/src/logger.spec.ts

@@ -0,0 +1,128 @@
+/**
+ * @fileoverview Tests for Logger.
+ * Logger のテスト。
+ */
+
+import { beforeEach, describe, expect, it, vi } from "vitest"
+import { type ILogger, Logger, LogLevel } from "./logger"
+
+const createImpl = (): ILogger => ({
+    debug: vi.fn(),
+    info: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+})
+
+describe("Logger", () => {
+    let impl: ILogger
+
+    beforeEach(() => {
+        impl = createImpl()
+    })
+
+    it("レベル抑制時は impl を呼ばない", () => {
+        const logger = new Logger(LogLevel.WARN, "[t]", impl)
+        logger.debug("hidden")
+        logger.info("hidden")
+        expect(impl.debug).not.toHaveBeenCalled()
+        expect(impl.info).not.toHaveBeenCalled()
+    })
+
+    it("有効レベルでは prefix 付きで出力する(後方互換)", () => {
+        const logger = new Logger(LogLevel.DEBUG, "[t]", impl)
+        logger.debug("hello", 1, 2)
+        expect(impl.debug).toHaveBeenCalledWith("[t] hello", 1, 2)
+
+        logger.warn({ a: 1 })
+        expect(impl.warn).toHaveBeenCalledWith("[t]", { a: 1 })
+    })
+
+    describe("isEnabled", () => {
+        it("現在のレベルで出力されるレベルのみ true", () => {
+            const logger = new Logger(LogLevel.WARN, "[t]", impl)
+            expect(logger.isEnabled(LogLevel.DEBUG)).toBe(false)
+            expect(logger.isEnabled(LogLevel.INFO)).toBe(false)
+            expect(logger.isEnabled(LogLevel.WARN)).toBe(true)
+            expect(logger.isEnabled(LogLevel.ERROR)).toBe(true)
+        })
+
+        it("静的インスタンスにも isEnabled がある", () => {
+            Logger.setLevel(LogLevel.ERROR)
+            expect(Logger.isEnabled(LogLevel.WARN)).toBe(false)
+            expect(Logger.isEnabled(LogLevel.ERROR)).toBe(true)
+            Logger.setLevel(LogLevel.WARN)
+        })
+    })
+
+    describe("遅延評価(サンク)引数", () => {
+        it("抑制時はサンクを一切呼ばない(オブジェクト生成/DOM 読み取りを回避)", () => {
+            const logger = new Logger(LogLevel.WARN, "[t]", impl)
+            const messageThunk = vi.fn(() => "expensive message")
+            const paramThunk = vi.fn(() => ({ heavy: true }))
+
+            logger.debug(messageThunk, paramThunk)
+
+            expect(messageThunk).not.toHaveBeenCalled()
+            expect(paramThunk).not.toHaveBeenCalled()
+            expect(impl.debug).not.toHaveBeenCalled()
+        })
+
+        it("有効時はサンクを解決して出力する", () => {
+            const logger = new Logger(LogLevel.DEBUG, "[t]", impl)
+            const messageThunk = vi.fn(() => "expensive message")
+            const paramThunk = vi.fn(() => ({ heavy: true }))
+
+            logger.debug(messageThunk, paramThunk)
+
+            expect(messageThunk).toHaveBeenCalledTimes(1)
+            expect(paramThunk).toHaveBeenCalledTimes(1)
+            expect(impl.debug).toHaveBeenCalledWith("[t] expensive message", { heavy: true })
+        })
+
+        it("非関数値はそのまま素通し(後方互換)", () => {
+            const logger = new Logger(LogLevel.INFO, "[t]", impl)
+            logger.info("plain", { a: 1 }, 3)
+            expect(impl.info).toHaveBeenCalledWith("[t] plain", { a: 1 }, 3)
+        })
+
+        it("class を渡してもクラッシュせず、元のクラス値をそのまま出力する", () => {
+            const logger = new Logger(LogLevel.ERROR, "[t]", impl)
+            class Foo {}
+
+            // class constructor は `new` なしで呼べないが、logger 呼び出しは throw しない
+            expect(() => logger.error("failed with handler:", Foo)).not.toThrow()
+            expect(impl.error).toHaveBeenCalledWith("[t] failed with handler:", Foo)
+
+            // message 位置に class を渡してもクラッシュしない
+            expect(() => logger.error(Foo)).not.toThrow()
+            expect(impl.error).toHaveBeenCalledWith("[t]", Foo)
+        })
+
+        it("thunk が throw しても例外を伝播させず、元の関数値を出力する", () => {
+            const logger = new Logger(LogLevel.DEBUG, "[t]", impl)
+            const badThunk = () => {
+                throw new Error("boom in thunk")
+            }
+
+            // レベル有効時でもログ呼び出しは呼び出し元に例外を伝播させない
+            expect(() => logger.debug("state:", badThunk)).not.toThrow()
+            // 握り潰しではなく、元の関数値がログに出力される
+            expect(impl.debug).toHaveBeenCalledWith("[t] state:", badThunk)
+
+            // message 位置の thunk が throw するケースも同様
+            expect(() => logger.debug(badThunk)).not.toThrow()
+            expect(impl.debug).toHaveBeenCalledWith("[t]", badThunk)
+        })
+
+        it("抑制レベルでは throw する thunk も一切評価されない", () => {
+            const logger = new Logger(LogLevel.WARN, "[t]", impl)
+            const badThunk = vi.fn(() => {
+                throw new Error("boom in thunk")
+            })
+
+            expect(() => logger.debug(badThunk)).not.toThrow()
+            expect(badThunk).not.toHaveBeenCalled()
+            expect(impl.debug).not.toHaveBeenCalled()
+        })
+    })
+})

package/src/logger.ts

@@ -0,0 +1,229 @@
+/**
+ * @module utils/logger
+ * @description Logger utility for consistent log management across the library.
+ * @description ライブラリ全体で一貫したログ管理を行うためのロガーユーティリティ。
+ */
+
+/**
+ * @enum LogLevel
+ * @description Log levels for filtering output.
+ * @description 出力をフィルタリングするためのログレベル。
+ */
+export 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 class Logger implements ILogger {
+    private level: LogLevel
+    private prefix: string
+    private impl: ILogger
+
+    /**
+     * @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 = LogLevel.WARN, prefix: string = "[virtualscroll]", impl: ILogger = console) {
+        this.level = level
+        this.prefix = prefix
+        this.impl = impl
+    }
+
+    private static instance: Logger = new Logger(LogLevel.WARN, "[virtualscroll]")
+
+    /**
+     * @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 {
+        Logger.instance.setLevel(level)
+    }
+
+    /**
+     * @method setLevel
+     * @description Updates the current log level.
+     * @description 現在のログレベルを更新します。
+     * @param {LogLevel} level - The new log level.
+     */
+    setLevel(level: LogLevel): void {
+        this.level = level
+    }
+
+    /**
+     * @method setImplementation
+     * @description Updates the logger implementation for the static instance.
+     * @description 静的インスタンスのロガーの実装を更新します。
+     * @param {ILogger} impl - The new logger implementation.
+     */
+    static setImplementation(impl: ILogger): void {
+        Logger.instance.setImplementation(impl)
+    }
+
+    /**
+     * @method setImplementation
+     * @description Updates the logger implementation.
+     * @description ロガーの実装を更新します。
+     * @param {ILogger} impl - The new logger implementation.
+     */
+    setImplementation(impl: ILogger): void {
+        this.impl = impl
+    }
+
+    /**
+     * @method setPrefix
+     * @description Updates the log prefix for the static instance.
+     * @description 静的インスタンスのログのプレフィックスを更新します。
+     * @param {string} prefix - The new prefix.
+     */
+    static setPrefix(prefix: string): void {
+        Logger.instance.setPrefix(prefix)
+    }
+
+    /**
+     * @method setPrefix
+     * @description Updates the log prefix.
+     * @description ログのプレフィックスを更新します。
+     * @param {string} prefix - The new prefix.
+     */
+    setPrefix(prefix: string): void {
+        this.prefix = prefix
+    }
+
+    /**
+     * @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 {
+        return Logger.instance.isEnabled(level)
+    }
+
+    /**
+     * @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 {
+        return this.level <= level
+    }
+
+    /**
+     * 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(value: unknown): unknown {
+        // 非関数値はそのまま素通し (後方互換)
+        if (typeof value !== "function") {
+            return value
+        }
+        try {
+            // 関数は thunk とみなして遅延評価する
+            return (value as () => unknown)()
+        } catch {
+            // class constructor や失敗した thunk は元の関数値をそのまま出力対象にする
+            return value
+        }
+    }
+
+    private formatMessage(message: unknown): unknown[] {
+        if (typeof message === "string") {
+            return [`${this.prefix} ${message}`]
+        }
+        return [this.prefix, message]
+    }
+
+    static debug(message?: unknown, ...optionalParams: unknown[]): void {
+        Logger.instance.debug(message, ...optionalParams)
+    }
+
+    debug(message?: unknown, ...optionalParams: unknown[]): void {
+        if (this.level <= LogLevel.DEBUG) {
+            this.impl.debug(...this.formatMessage(Logger.resolveLazy(message)), ...optionalParams.map(Logger.resolveLazy))
+        }
+    }
+
+    static info(message?: unknown, ...optionalParams: unknown[]): void {
+        Logger.instance.info(message, ...optionalParams)
+    }
+
+    info(message?: unknown, ...optionalParams: unknown[]): void {
+        if (this.level <= LogLevel.INFO) {
+            this.impl.info(...this.formatMessage(Logger.resolveLazy(message)), ...optionalParams.map(Logger.resolveLazy))
+        }
+    }
+
+    static warn(message?: unknown, ...optionalParams: unknown[]): void {
+        Logger.instance.warn(message, ...optionalParams)
+    }
+
+    warn(message?: unknown, ...optionalParams: unknown[]): void {
+        if (this.level <= LogLevel.WARN) {
+            this.impl.warn(...this.formatMessage(Logger.resolveLazy(message)), ...optionalParams.map(Logger.resolveLazy))
+        }
+    }
+
+    static error(message?: unknown, ...optionalParams: unknown[]): void {
+        Logger.instance.error(message, ...optionalParams)
+    }
+
+    error(message?: unknown, ...optionalParams: unknown[]): void {
+        if (this.level <= LogLevel.ERROR) {
+            this.impl.error(...this.formatMessage(Logger.resolveLazy(message)), ...optionalParams.map(Logger.resolveLazy))
+        }
+    }
+}

package/src/styles/components.entry.css

@@ -0,0 +1,9 @@
+/*
+ * Artifact A: components-only CSS (Tailwind ホスト向け).
+ * 手書き .aqvs-* コンポーネントクラスのみ。:root テーマ変数・ユーティリティ・preflight を含まない。
+ * ホストは @import "@aiquants/virtualscroll/styles/virtualscroll.css" layer(components) で読み込む。
+ */
+@import "tailwindcss/theme.css" theme(reference);
+@layer components {
+  @import "./virtualscroll.css";
+}

package/src/styles/standalone.entry.css

@@ -0,0 +1,11 @@
+/*! @aiquants/virtualscroll standalone CSS — 非 Tailwind ホスト専用。ホストの Tailwind ビルドと混在させないこと */
+/*
+ * Artifact B: 自己完結スタンドアロン. virtualscroll は JSX ユーティリティを持たないため
+ * 実質 .aqvs-* コンポーネントクラスのみだが、命名統一のため standalone も配布する。
+ */
+@layer theme, base, components, utilities;
+@import "tailwindcss/theme.css" layer(theme);
+@import "tailwindcss/utilities.css" layer(utilities) source(none);
+@import "./virtualscroll.css" layer(components);
+@source "../**/*.{ts,tsx}";
+@custom-variant dark (&:where(.dark, .dark *));