momoi-explorer 0.8.0 → 0.8.3

package/README.md

@@ -1,355 +1,409 @@
-# momoi-explorer
-
-ヘッドレスファイルエクスプローラーライブラリ。フレームワーク非依存のコア + React バインディング + デフォルト UI の3層構成。
-
-## インストール
-
-```bash
-npm install momoi-explorer
-```
-
-## アーキテクチャ
-
-3つのエントリポイントを持つ段階的なアーキテクチャ:
-
-| エントリポイント | 用途 | React必須 |
-|---|---|---|
-| `momoi-explorer` | コアエンジン（フレームワーク非依存） | No |
-| `momoi-explorer/react` | React バインディング（hooks + context） | Yes |
-| `momoi-explorer/ui` | デフォルト UI コンポーネント | Yes |
-
-## クイックスタート
-
-### 1. FileSystemAdapter を実装する
-
-全ての始まりは `FileSystemAdapter` の実装。`readDir` のみ必須で、他のメソッドはオプション（実装すると対応機能が有効になる）。
-
-```ts
-import type { FileSystemAdapter } from 'momoi-explorer'
-
-const adapter: FileSystemAdapter = {
-  // 必須: ディレクトリの中身を返す
-  async readDir(dirPath) {
-    const entries = await fs.readdir(dirPath, { withFileTypes: true })
-    return entries.map(e => ({
-      name: e.name,
-      path: path.join(dirPath, e.name),
-      isDirectory: e.isDirectory(),
-    }))
-  },
-  // オプション: リネーム
-  async rename(oldPath, newPath) {
-    await fs.rename(oldPath, newPath)
-  },
-  // オプション: 削除
-  async delete(paths) {
-    for (const p of paths) await fs.rm(p, { recursive: true })
-  },
-  // オプション: ファイル作成
-  async createFile(parentPath, name) {
-    await fs.writeFile(path.join(parentPath, name), '')
-  },
-  // オプション: フォルダ作成
-  async createDir(parentPath, name) {
-    await fs.mkdir(path.join(parentPath, name))
-  },
-  // オプション: ファイル監視（デバウンス・合体はコアが行う）
-  watch(dirPath, callback) {
-    const watcher = fs.watch(dirPath, { recursive: true }, (event, filename) => {
-      callback([{ type: event === 'rename' ? 'create' : 'modify', path: filename, isDirectory: false }])
-    })
-    return () => watcher.close()
-  },
-}
-```
-
-### 2a. デフォルト UI を使う（最も簡単）
-
-```tsx
-import { FileExplorer } from 'momoi-explorer/ui'
-import 'momoi-explorer/ui/style.css'
-
-function App() {
-  return (
-    <FileExplorer
-      adapter={adapter}
-      rootPath="/home/user/project"
-      onOpen={(path) => openFile(path)}
-      onEvent={(e) => console.log('tree event:', e)}
-      showFilterBar
-    />
-  )
-}
-```
-
-### 2b. React hooks でカスタム UI を構築する
-
-```tsx
-import { TreeProvider, useFileTree, useTreeNode } from 'momoi-explorer/react'
-
-function App() {
-  return (
-    <TreeProvider adapter={adapter} rootPath="/home/user/project">
-      <MyCustomTree />
-    </TreeProvider>
-  )
-}
-
-function MyCustomTree() {
-  const { flatList, controller } = useFileTree()
-
-  return (
-    <div>
-      {flatList.map(({ node, depth }) => (
-        <div key={node.path} style={{ paddingLeft: depth * 16 }}>
-          <span onClick={() => controller.toggleExpand(node.path)}>
-            {node.name}
-          </span>
-        </div>
-      ))}
-    </div>
-  )
-}
-```
-
-### 2c. コアのみ使用（フレームワーク非依存）
-
-```ts
-import { createFileTree } from 'momoi-explorer'
-
-const tree = createFileTree({
-  adapter,
-  rootPath: '/home/user/project',
-  onEvent: (e) => console.log(e),
-})
-
-// 状態購読
-tree.subscribe((state) => {
-  console.log('nodes:', state.rootNodes)
-  console.log('flatList:', state.flatList)
-})
-
-// ツリーを読み込み
-await tree.loadRoot()
-
-// 操作
-await tree.expand('/home/user/project/src')
-tree.select('/home/user/project/src/index.ts')
-tree.setSearchQuery('config')
-
-// 後始末
-tree.destroy()
-```
-
-## API リファレンス
-
-### コア層 (`momoi-explorer`)
-
-#### `createFileTree(options): FileTreeController`
-
-ヘッドレスファイルツリーのメインエントリポイント。
-
-**FileTreeOptions:**
-| プロパティ | 型 | 説明 |
-|---|---|---|
-| `adapter` | `FileSystemAdapter` | ファイルシステムアダプタ（必須） |
-| `rootPath` | `string` | ルートディレクトリの絶対パス |
-| `sort` | `(a, b) => number` | カスタムソート関数 |
-| `filter` | `(entry) => boolean` | カスタムフィルタ関数 |
-| `watchOptions` | `WatchOptions` | ファイル監視設定 |
-| `onEvent` | `(event: TreeEvent) => void` | イベントコールバック |
-
-**FileTreeController のメソッド:**
-
-| メソッド | 説明 |
-|---|---|
-| `getState()` | 現在の TreeState を取得 |
-| `subscribe(listener)` | 状態変更を購読。unsubscribe関数を返す |
-| `loadRoot()` | ルートを読み込み・初期化（最初に必ず呼ぶ） |
-| `expand(path)` | ディレクトリを展開 |
-| `collapse(path)` | ディレクトリを折りたたみ |
-| `toggleExpand(path)` | 展開/折りたたみをトグル |
-| `expandTo(path)` | 指定パスまで祖先をすべて展開 |
-| `select(path, mode?)` | ノードを選択（mode: 'replace' / 'toggle' / 'range'） |
-| `selectAll()` | 全ノードを選択 |
-| `clearSelection()` | 選択解除 |
-| `startRename(path)` | リネームモード開始 |
-| `commitRename(newName)` | リネーム確定 |
-| `cancelRename()` | リネームキャンセル |
-| `startCreate(parentPath, isDirectory)` | インライン新規作成モード開始 |
-| `commitCreate(name)` | 新規作成確定 |
-| `cancelCreate()` | 新規作成キャンセル |
-| `createFile(parentPath, name)` | ファイル作成 |
-| `createDir(parentPath, name)` | フォルダ作成 |
-| `deleteSelected()` | 選択中のアイテムを削除 |
-| `refresh(path?)` | ツリーをリフレッシュ（展開状態は保持） |
-| `setSearchQuery(query)` | ファジー検索クエリ設定（nullで解除） |
-| `collectAllFiles()` | 全ファイルを再帰収集（QuickOpen用） |
-| `setFilter(fn)` | フィルタ関数を動的変更 |
-| `setSort(fn)` | ソート関数を動的変更 |
-| `destroy()` | コントローラ破棄（監視停止・購読解除） |
-
-#### ユーティリティ関数
-
-| 関数 | 説明 |
-|---|---|
-| `flattenTree(nodes, expandedPaths, matchingPaths?)` | ツリーをフラットリストに変換 |
-| `computeSelection(current, anchor, target, mode, flatList)` | 選択状態を計算 |
-| `fuzzyMatch(query, target)` | ファジーマッチ（match + score） |
-| `fuzzyFind(files, query, maxResults?)` | スコア順にファジー検索 |
-| `findMatchingPaths(nodes, query)` | マッチするパスのSetを返す |
-| `coalesceEvents(raw)` | 生イベントを合体処理 |
-| `createEventProcessor(callback, options?)` | デバウンス付きイベントプロセッサ |
-| `defaultSort(a, b)` | デフォルトソート（フォルダ優先・名前昇順） |
-| `defaultFilter(entry)` | デフォルトフィルタ（全表示） |
-
-### React層 (`momoi-explorer/react`)
-
-| エクスポート | 種別 | 説明 |
-|---|---|---|
-| `TreeProvider` | コンポーネント | ファイルツリーのコンテキストプロバイダー。内部で `createFileTree` + `loadRoot` を行う |
-| `useFileTree()` | Hook | ツリー全体の状態とコントローラを返す |
-| `useTreeNode(path)` | Hook | 個別ノードの展開/選択/リネーム状態を返す（見つからない場合 null） |
-| `useContextMenu()` | Hook | 右クリックメニューの表示制御（show/hide + 座標管理） |
-| `useTreeContext()` | Hook | TreeContext の生の値を取得（通常は useFileTree を使う） |
-
-### UI層 (`momoi-explorer/ui`)
-
-| エクスポート | 説明 |
-|---|---|
-| `FileExplorer` | オールインワンコンポーネント（TreeProvider内包、仮想スクロール、コンテキストメニュー対応） |
-| `TreeNodeRow` | ツリーの1行コンポーネント（アイコン、インデント、選択、リネーム対応） |
-| `ContextMenu` | 右クリックメニュー（外側クリック/Escで閉じる） |
-| `InlineRename` | インライン名前変更input（Enter確定、Escキャンセル） |
-| `TreeFilterBar` | ファジー検索フィルタバー |
-| `QuickOpen` | VSCode風クイックオープンダイアログ（Ctrl+P相当） |
-
-**スタイル:**
-
-```ts
-import 'momoi-explorer/ui/style.css'
-```
-
-VSCode風ダークテーマ。CSS変数やクラス名（`.momoi-explorer-*`）でカスタマイズ可能。
-
-### FileExplorer の Props
-
-```tsx
-<FileExplorer
-  adapter={adapter}            // FileSystemAdapter（必須）
-  rootPath="/path/to/dir"      // ルートパス（必須）
-  sort={(a, b) => ...}         // カスタムソート
-  filter={(entry) => ...}      // カスタムフィルタ
-  watchOptions={{ ... }}       // ファイル監視設定
-  onEvent={(e) => ...}         // ツリーイベントコールバック
-  onOpen={(path) => ...}       // ファイルダブルクリック時
-  renderIcon={(node, expanded) => ...}   // カスタムアイコン
-  renderBadge={(node) => ...}  // カスタムバッジ（git status等）
-  contextMenuItems={(nodes) => [...]}    // コンテキストメニュー項目
-  showFilterBar                // フィルタバー表示
-  onControllerReady={(ctrl) => ...}      // コントローラ参照の取得
-  className="my-explorer"      // CSSクラス
-  style={{ height: 400 }}      // インラインスタイル
-/>
-```
-
-### QuickOpen の使い方
-
-```tsx
-import { FileExplorer, QuickOpen } from 'momoi-explorer/ui'
-
-function App() {
-  const [ctrl, setCtrl] = useState<FileTreeController | null>(null)
-  const [quickOpen, setQuickOpen] = useState(false)
-
-  return (
-    <>
-      <FileExplorer
-        adapter={adapter}
-        rootPath={rootPath}
-        onControllerReady={setCtrl}
-      />
-      {ctrl && (
-        <QuickOpen
-          controller={ctrl}
-          isOpen={quickOpen}
-          onClose={() => setQuickOpen(false)}
-          onSelect={(entry) => openFile(entry.path)}
-        />
-      )}
-    </>
-  )
-}
-```
-
-## 主要な型
-
-```ts
-interface FileEntry {
-  name: string          // ファイル名
-  path: string          // 絶対パス
-  isDirectory: boolean  // ディレクトリか
-  meta?: Record<string, unknown>  // 拡張用メタデータ
-}
-
-interface TreeNode extends FileEntry {
-  depth: number
-  children?: TreeNode[]
-  childrenLoaded: boolean
-}
-
-interface FlatNode {
-  node: TreeNode
-  depth: number
-}
-
-interface TreeState {
-  rootPath: string
-  rootNodes: TreeNode[]
-  expandedPaths: Set<string>
-  selectedPaths: Set<string>
-  anchorPath: string | null
-  renamingPath: string | null
-  creatingState: CreatingState | null
-  searchQuery: string | null
-  flatList: FlatNode[]
-}
-
-type TreeEvent =
-  | { type: 'expand'; path: string }
-  | { type: 'collapse'; path: string }
-  | { type: 'select'; paths: string[] }
-  | { type: 'open'; path: string }
-  | { type: 'rename'; oldPath: string; newPath: string }
-  | { type: 'delete'; paths: string[] }
-  | { type: 'create'; parentPath: string; name: string; isDirectory: boolean }
-  | { type: 'refresh'; path?: string }
-  | { type: 'external-change'; changes: WatchEvent[] }
-```
-
-## ファイル監視
-
-`adapter.watch` を実装すると自動でファイル監視が有効になる。生イベントをそのまま投げるだけでよく、以下の処理はコアが自動で行う:
-
-- **デバウンス** (75ms, VSCode準拠)
-- **イベント合体**: rename → delete+create、delete+create(同一パス) → modify、親フォルダ削除時に子イベント除去
-- **スロットリング**: 大量イベント時にチャンク分割（500件/200ms間隔）
-
-```ts
-const tree = createFileTree({
-  adapter,
-  rootPath: '/project',
-  watchOptions: {
-    debounceMs: 100,        // デフォルト: 75
-    coalesce: true,         // デフォルト: true
-    throttle: {
-      maxChunkSize: 1000,   // デフォルト: 500
-      delayMs: 300,         // デフォルト: 200
-    },
-  },
-})
-```
-
-## ライセンス
-
-MIT
+# momoi-explorer
+
+> Built with [Claude Code](https://claude.com/claude-code) by Anthropic.
+
+A headless file explorer library. Framework-agnostic core + React bindings + default UI in a 3-layer architecture.
+
+## Install
+
+```bash
+npm install momoi-explorer
+```
+
+## Architecture
+
+Three entry points with a layered architecture:
+
+| Entry Point | Purpose | Requires React |
+|---|---|---|
+| `momoi-explorer` | Core engine (framework-agnostic) | No |
+| `momoi-explorer/react` | React bindings (hooks + context) | Yes |
+| `momoi-explorer/ui` | Default UI components | Yes |
+
+## Quick Start
+
+### 1. Implement a FileSystemAdapter
+
+Everything starts with implementing `FileSystemAdapter`. Only `readDir` is required; other methods are optional (implementing them enables the corresponding features).
+
+```ts
+import type { FileSystemAdapter } from 'momoi-explorer'
+
+const adapter: FileSystemAdapter = {
+  // Required: return directory contents
+  async readDir(dirPath) {
+    const entries = await fs.readdir(dirPath, { withFileTypes: true })
+    return entries.map(e => ({
+      name: e.name,
+      path: path.join(dirPath, e.name),
+      isDirectory: e.isDirectory(),
+    }))
+  },
+  // Optional: rename
+  async rename(oldPath, newPath) {
+    await fs.rename(oldPath, newPath)
+  },
+  // Optional: delete
+  async delete(paths) {
+    for (const p of paths) await fs.rm(p, { recursive: true })
+  },
+  // Optional: create file
+  async createFile(parentPath, name) {
+    await fs.writeFile(path.join(parentPath, name), '')
+  },
+  // Optional: create directory
+  async createDir(parentPath, name) {
+    await fs.mkdir(path.join(parentPath, name))
+  },
+  // Optional: file watching (debounce & coalescing handled by core)
+  watch(dirPath, callback) {
+    const watcher = fs.watch(dirPath, { recursive: true }, (event, filename) => {
+      callback([{ type: event === 'rename' ? 'create' : 'modify', path: filename, isDirectory: false }])
+    })
+    return () => watcher.close()
+  },
+}
+```
+
+### 2a. Use the Default UI (easiest)
+
+```tsx
+import { FileExplorer } from 'momoi-explorer/ui'
+import 'momoi-explorer/ui/style.css'
+
+function App() {
+  return (
+    <FileExplorer
+      adapter={adapter}
+      rootPath="/home/user/project"
+      onOpen={(path) => openFile(path)}
+      onEvent={(e) => console.log('tree event:', e)}
+      showFilterBar
+    />
+  )
+}
+```
+
+### 2b. Build Custom UI with React Hooks
+
+```tsx
+import { TreeProvider, useFileTree, useTreeNode } from 'momoi-explorer/react'
+
+function App() {
+  return (
+    <TreeProvider adapter={adapter} rootPath="/home/user/project">
+      <MyCustomTree />
+    </TreeProvider>
+  )
+}
+
+function MyCustomTree() {
+  const { flatList, controller } = useFileTree()
+
+  return (
+    <div>
+      {flatList.map(({ node, depth }) => (
+        <div key={node.path} style={{ paddingLeft: depth * 16 }}>
+          <span onClick={() => controller.toggleExpand(node.path)}>
+            {node.name}
+          </span>
+        </div>
+      ))}
+    </div>
+  )
+}
+```
+
+### 2c. Core Only (framework-agnostic)
+
+```ts
+import { createFileTree } from 'momoi-explorer'
+
+const tree = createFileTree({
+  adapter,
+  rootPath: '/home/user/project',
+  onEvent: (e) => console.log(e),
+})
+
+// Subscribe to state changes
+tree.subscribe((state) => {
+  console.log('nodes:', state.rootNodes)
+  console.log('flatList:', state.flatList)
+})
+
+// Load the tree
+await tree.loadRoot()
+
+// Operations
+await tree.expand('/home/user/project/src')
+tree.select('/home/user/project/src/index.ts')
+tree.setSearchQuery('config')
+
+// Cleanup
+tree.destroy()
+```
+
+## API Reference
+
+### Core (`momoi-explorer`)
+
+#### `createFileTree(options): FileTreeController`
+
+Main entry point for the headless file tree.
+
+**FileTreeOptions:**
+| Property | Type | Description |
+|---|---|---|
+| `adapter` | `FileSystemAdapter` | File system adapter (required) |
+| `rootPath` | `string` | Absolute path to the root directory |
+| `sort` | `(a, b) => number` | Custom sort function |
+| `filter` | `(entry) => boolean` | Custom filter function |
+| `watchOptions` | `WatchOptions` | File watching options |
+| `onEvent` | `(event: TreeEvent) => void` | Event callback |
+
+**FileTreeController Methods:**
+
+| Method | Description |
+|---|---|
+| `getState()` | Get current TreeState |
+| `subscribe(listener)` | Subscribe to state changes. Returns unsubscribe function |
+| `loadRoot()` | Load and initialize root (must be called first) |
+| `expand(path)` | Expand a directory |
+| `collapse(path)` | Collapse a directory |
+| `toggleExpand(path)` | Toggle expand/collapse |
+| `expandTo(path)` | Expand all ancestors up to the given path |
+| `select(path, mode?)` | Select a node (mode: 'replace' / 'toggle' / 'range') |
+| `selectAll()` | Select all nodes |
+| `clearSelection()` | Clear selection |
+| `startRename(path)` | Enter rename mode |
+| `commitRename(newName)` | Commit rename |
+| `cancelRename()` | Cancel rename |
+| `startCreate(parentPath, isDirectory, insertAfterPath?)` | Enter inline creation mode (insertAfterPath: position for the input row) |
+| `commitCreate(name)` | Commit creation |
+| `cancelCreate()` | Cancel creation |
+| `createFile(parentPath, name)` | Create a file |
+| `createDir(parentPath, name)` | Create a directory |
+| `deleteSelected()` | Delete selected items |
+| `refresh(path?)` | Refresh the tree (preserves expanded state) |
+| `setSearchQuery(query)` | Set fuzzy search query (null to clear) |
+| `collectAllFiles()` | Recursively collect all files (for QuickOpen) |
+| `setFilter(fn)` | Dynamically change the filter function |
+| `setSort(fn)` | Dynamically change the sort function |
+| `destroy()` | Destroy the controller (stops watching, clears subscriptions) |
+
+#### Utility Functions
+
+| Function | Description |
+|---|---|
+| `flattenTree(nodes, expandedPaths, matchingPaths?)` | Convert tree to flat list |
+| `computeSelection(current, anchor, target, mode, flatList)` | Compute selection state |
+| `fuzzyMatch(query, target)` | Fuzzy match (match + score) |
+| `fuzzyFind(files, query, maxResults?)` | Fuzzy search sorted by score |
+| `findMatchingPaths(nodes, query)` | Return Set of matching paths |
+| `coalesceEvents(raw)` | Coalesce raw watch events |
+| `createEventProcessor(callback, options?)` | Event processor with debounce |
+| `defaultSort(a, b)` | Default sort (directories first, name ascending) |
+| `defaultFilter(entry)` | Default filter (show all) |
+| `ExplorerCommands` | Explorer command ID constants (DELETE, RENAME, etc.) |
+| `defaultExplorerKeybindings` | Default keybinding definitions (for momoi-keybind) |
+
+### React (`momoi-explorer/react`)
+
+| Export | Kind | Description |
+|---|---|---|
+| `TreeProvider` | Component | File tree context provider. Calls `createFileTree` + `loadRoot` internally |
+| `useFileTree()` | Hook | Returns full tree state and controller |
+| `useTreeNode(path)` | Hook | Returns expand/select/rename state for a node (null if not found) |
+| `useContextMenu()` | Hook | Context menu visibility control (show/hide + position) |
+| `useExplorerKeybindings(inputService)` | Hook | momoi-keybind integration. Registers explorer command handlers |
+| `useExplorerFocus(inputService)` | Hook | Syncs focus state with momoi-keybind context |
+| `useTreeContext()` | Hook | Raw TreeContext value (usually use useFileTree instead) |
+
+### UI (`momoi-explorer/ui`)
+
+| Export | Description |
+|---|---|
+| `FileExplorer` | All-in-one component (includes TreeProvider, virtual scrolling, context menu) |
+| `TreeNodeRow` | Single tree row (icon, indent, selection, rename) |
+| `ContextMenu` | Right-click menu (closes on outside click/Esc) |
+| `InlineRename` | Inline rename input (Enter to confirm, Esc to cancel) |
+| `TreeFilterBar` | Fuzzy search filter bar |
+| `QuickOpen` | VSCode-style quick open dialog (Ctrl+P equivalent) |
+
+**Styles:**
+
+```ts
+import 'momoi-explorer/ui/style.css'
+```
+
+VSCode-style dark theme. Customizable via CSS variables and class names (`.momoi-explorer-*`).
+
+### FileExplorer Props
+
+```tsx
+<FileExplorer
+  adapter={adapter}            // FileSystemAdapter (required)
+  rootPath="/path/to/dir"      // Root path (required)
+  sort={(a, b) => ...}         // Custom sort
+  filter={(entry) => ...}      // Custom filter
+  watchOptions={{ ... }}       // File watching options
+  onEvent={(e) => ...}         // Tree event callback
+  onOpen={(path) => ...}       // File double-click handler
+  renderIcon={(node, expanded) => ...}   // Custom icon renderer
+  renderBadge={(node) => ...}  // Custom badge renderer (e.g. git status)
+  contextMenuItems={(nodes) => [...]}    // Context menu items
+  showFilterBar                // Show filter bar
+  onControllerReady={(ctrl) => ...}      // Get controller reference
+  inputService={inputService}  // momoi-keybind InputService instance (optional)
+  onKeyDown={(e) => ...}       // Key event handler when not using momoi-keybind
+  className="my-explorer"      // CSS class
+  style={{ height: 400 }}      // Inline styles
+/>
+```
+
+### QuickOpen Usage
+
+```tsx
+import { FileExplorer, QuickOpen } from 'momoi-explorer/ui'
+
+function App() {
+  const [ctrl, setCtrl] = useState<FileTreeController | null>(null)
+  const [quickOpen, setQuickOpen] = useState(false)
+
+  return (
+    <>
+      <FileExplorer
+        adapter={adapter}
+        rootPath={rootPath}
+        onControllerReady={setCtrl}
+      />
+      {ctrl && (
+        <QuickOpen
+          controller={ctrl}
+          isOpen={quickOpen}
+          onClose={() => setQuickOpen(false)}
+          onSelect={(entry) => openFile(entry.path)}
+        />
+      )}
+    </>
+  )
+}
+```
+
+## Key Types
+
+```ts
+interface FileEntry {
+  name: string          // File name
+  path: string          // Absolute path
+  isDirectory: boolean  // Is directory
+  meta?: Record<string, unknown>  // Extension metadata
+}
+
+interface TreeNode extends FileEntry {
+  depth: number
+  children?: TreeNode[]
+  childrenLoaded: boolean
+}
+
+interface FlatNode {
+  node: TreeNode
+  depth: number
+}
+
+interface TreeState {
+  rootPath: string
+  rootNodes: TreeNode[]
+  expandedPaths: Set<string>
+  selectedPaths: Set<string>
+  anchorPath: string | null
+  renamingPath: string | null
+  creatingState: CreatingState | null
+  searchQuery: string | null
+  flatList: FlatNode[]
+}
+
+type TreeEvent =
+  | { type: 'expand'; path: string }
+  | { type: 'collapse'; path: string }
+  | { type: 'select'; paths: string[] }
+  | { type: 'open'; path: string }
+  | { type: 'rename'; oldPath: string; newPath: string }
+  | { type: 'delete'; paths: string[] }
+  | { type: 'create'; parentPath: string; name: string; isDirectory: boolean }
+  | { type: 'refresh'; path?: string }
+  | { type: 'external-change'; changes: WatchEvent[] }
+```
+
+## File Watching
+
+Implementing `adapter.watch` automatically enables file watching. Just emit raw events; the core handles:
+
+- **Debounce** (75ms, VSCode-compatible)
+- **Event coalescing**: rename → delete+create, delete+create (same path) → modify, child events removed on parent delete
+- **Throttling**: Chunk splitting for large batches (500 events / 200ms interval)
+
+```ts
+const tree = createFileTree({
+  adapter,
+  rootPath: '/project',
+  watchOptions: {
+    debounceMs: 100,        // Default: 75
+    coalesce: true,         // Default: true
+    throttle: {
+      maxChunkSize: 1000,   // Default: 500
+      delayMs: 300,         // Default: 200
+    },
+  },
+})
+```
+
+## Keybinding Integration (momoi-keybind)
+
+When `momoi-keybind` is installed, pass an `inputService` prop to enable keybindings. `momoi-keybind` is an optional peer dependency.
+
+```tsx
+import { InputService } from 'momoi-keybind'
+import { defaultExplorerKeybindings } from 'momoi-explorer'
+import { FileExplorer } from 'momoi-explorer/ui'
+
+const inputService = new InputService({
+  defaultKeybindings: defaultExplorerKeybindings,
+})
+inputService.start()
+
+<FileExplorer
+  adapter={adapter}
+  rootPath={rootPath}
+  inputService={inputService}
+/>
+```
+
+**Default Keybindings:**
+
+| Key | Command |
+|---|---|
+| `Delete` | Delete selected items |
+| `F2` | Rename |
+| `Ctrl+N` | New file |
+| `Ctrl+Shift+N` | New folder |
+| `Ctrl+R` | Refresh |
+| `Ctrl+Shift+E` | Collapse all folders |
+| `Ctrl+A` | Select all |
+| `Ctrl+Shift+C` | Copy path |
+
+Override, add, or disable keybindings on the user side:
+
+```ts
+const inputService = new InputService({
+  defaultKeybindings: defaultExplorerKeybindings,
+  userKeybindings: [
+    { key: 'F2', command: 'myApp.quickPreview', when: 'explorerFocus' }, // Override
+    { key: '', command: '-explorer.delete' },  // Disable
+  ],
+})
+```
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "momoi-explorer",
-  "version": "0.8.0",
+  "version": "0.8.3",
   "description": "A headless file explorer component with React bindings and default UI",
   "author": "Waik0",
   "license": "MIT",