API Reference

Design principles

These constraints shape every public type. Read them once; they explain the rest of the API.

Principle		What it means for you
Tree in Rust		Canonical structure, watch, walk, and search live natively. JS owns expansion, selection, scroll.
Snapshot reads		All sync reads go through an immutable `MirrorSnapshot`. Safe during React render; identity-stable until the next change.
Flat over nested		Rows and entries cross NAPI as flat records. Virtualizers never walk a nested object tree.
Stable EntryId		Session-scoped ids stay stable across renames/moves. Capped at `2^53-1` for JS safety.
Typed errors		Expected FS failures throw `FileSystemError` with POSIX-like codes — use try/catch, not Result unions.
Version channels		`treeVersion` and `decorationVersion` bump independently so SCM churn does not thrash row caches.

Module entries

Import only what you need. Host code never belongs in the renderer bundle.

@vibecook/mille FileExplorer, errors, decorations, connect helpers

@vibecook/mille/host createFileExplorerHost — UtilityProcess only

@vibecook/mille/client connectFileExplorer, PortFileExplorer

@vibecook/mille/react useFileExplorerSnapshot

@vibecook/mille-ui Styled FileTree + hooks

@vibecook/mille-ui/headless Structure only · ~12.5 KB gzip

@vibecook/mille-ui/git Git decoration provider (browser-safe)

@vibecook/mille-ui/git/node createShellGitClient — Node/utility only

Core types

Shared identifiers and records used across engine and UI.

EntryId type

type EntryId = number

Monotonic id assigned in Rust. Stable across renames and moves within a session. Reassigned on process boot. Safe as a React key, Map key, or JSON value.

Uri interface

Scheme-based resource locator. Mirrors VS Code’s Uri shape. Local mode typically accepts absolute path strings as a convenience; hosts may pass full Uris.

Field	Type	Notes
scheme	string	`file` \| `memfs` \| `ssh` \| …
authority?	string	Remote host, etc.
path	string	Always POSIX-style
query?	string
fragment?	string

EntryKind enum

Member	Value
File	0
Directory	1
Symlink	2
Unknown	3

Entry interface

One row in the flat-array model

Field	Type	Notes
id	EntryId
parentId	EntryId \| null	`null` only for roots
name	string	Basename
kind	EntryKind	Numeric enum
size	number	Bytes; 0 for directories
mtimeMs	number	Unix ms
ctimeMs	number	Unix ms
symlinkTargetIsDir?	boolean	For UI caret rendering
pathSegments?	string[]	Set when compact-folders collapses a chain
isIgnored	boolean	Matched by ignore rules
isReadonly	boolean
isHidden	boolean	Dotfile or platform-hidden

Capability const enum

Bitmask providers advertise. Local mode currently reports ReadWrite | CaseSensitive | Watch.

Flag	Value
ReadWrite	1 << 0
CaseSensitive	1 << 1
Readonly	1 << 2
Trash	1 << 3
AtomicWrite	1 << 4
Watch	1 << 5
Stream	1 << 6
Clone	1 << 7
Realpath	1 << 8
FileLock	1 << 9

FileSystemError class

class FileSystemError extends Error

Expected filesystem failures. Check with isFileSystemError(e).

Member	Type	Notes
code	ErrorCode	EACCES, ENOENT, EEXIST, EISDIR, ENOTDIR, ELOOP, ENOSPC, EROFS, EBUSY, EINVAL, ECANCELED, EUNSUPPORTED, EUNKNOWN
path?	string	Path involved in the failure

try {
  await fx.rename(id, 'new-name');
} catch (e) {
  if (isFileSystemError(e) && e.code === 'EEXIST') {
    // handle collision
  } else throw e;
}

Explorer

Construct, populate, snapshot, mutate. Construction never walks the filesystem.

ExplorerOptions interface

Field	Type	Default / notes
roots	readonly (Uri \| string)[]	Required. Absolute paths or Uris.
respectIgnore?	boolean	`true` — parse .gitignore / .ignore / .rgignore
followSymlinks?	boolean \| 'smart'	`'smart'` — canonicalize, dedupe, block cycles
walkerConcurrency?	number	num_cpus
watchDebounceMs?	number	`75`
compactFolders?	boolean	`true`
excludeGlobs?	string[]	Extra excludes layered on ignore
snapshotPath?	string	Crash-resume snapshot file
maxCachedEntries?	number	`500_000`
initialWalk?	'full' \| 'roots-only' \| 'none'	Host walk policy. `'roots-only'` for huge repos. Default `'full'` (host does not auto-walk; caller populates).

FileExplorer class

new FileExplorer(options: ExplorerOptions)

Read path: getSnapshot() → sync queries on the snapshot.
Write path: methods on the explorer (create, rename, …).
Subscribe: on('change', …) with useSyncExternalStore.

getSnapshot(): MirrorSnapshot

Current immutable snapshot. Identity-stable until the next change event.

populateFromRoots(): Promise<number>

Parallel walk of configured roots. Returns total entry count. Call once after construction for full load.

setExpanded(diff: { add?: EntryId[]; remove?: EntryId[] }): void

Update session expansion. Host may trigger shallow walks for newly expanded folders (lazy list-on-expand).

setViewport(opts: { offset; limit; overscan? }): void

Declare the visible window so the host can prioritize mirror rows.

list(parentId, options?): Promise<ListPage>

Async paginated children. Prefer snapshot for already-loaded data.

prefetch(id, options?): Promise<void>

Warm children without adding to the expansion set.

create / rename / move / delete / copy

Structural mutations. Reject with FileSystemError on expected failures.

readFile / readText / writeFile / readFileStream

I/O by EntryId. Stream is AsyncIterable<Uint8Array>.

search(query, options?): Promise<SearchHit[]>

Fuzzy filename search over the in-memory tree (nucleo).

on(event, listener): Disposable

Events: change, change:tree, change:decorations, event, batch, warning, error, ready.

registerDecorationProvider(provider): Disposable

SCM / lint / problems overlay. Reads via snapshot.getDecorations(id).

writeSnapshot(path): Promise<void>

Persist crash-resume snapshot.

dispose(): Promise<void>

Stop watcher threads, release native resources. Idempotent.

MirrorSnapshot interface

Immutable view at a specific tree-version + decoration-version. Never mutate. Diff with ===.

readonly treeVersion: number

Structural version.

readonly decorationVersion: number

Decoration channel version.

roots(): readonly Entry[]

Workspace roots in display order.

visibleRows(options): readonly VisibleRow[]

Flat slice for virtualizers: expanded set + offset/limit. Cache-miss rows may set pending: true.

visibleRowCount(expanded, includeIgnored?): VisibleRowCount

known count plus pendingExpansions for incomplete folders.

getById / directChildCount / hasChildren / getDecorations

Point queries for rows and overlays.

const rows = snap.visibleRows({
  expanded,
  offset: 0,
  limit: 100,
  includeIgnored: false,
});

VisibleRow interface

extends Entry

Field	Type	Notes
depth	number	0 = root level
hasChildren	boolean	Caret affordance
isExpanded	boolean	From the query’s expansion set
pending?	true	Placeholder while children load

ChangeNotice interface

Payload for on('change' | 'change:tree' | 'change:decorations'). Pull model: bump version, re-read only the rows you need.

Field	Type	Notes
treeVersion	number
decorationVersion	number
changed	{ tree; decorations }	Which dimensions moved
changedIds	EntryId[]	Entries that may have changed
childSetChanged	EntryId[]	Parents whose children changed
decorationChangedIds	EntryId[]	Decoration-only updates
coarseSubtrees	EntryId[]	Watcher overflow regions

Host / client split

Recommended Electron deployment. Both sides satisfy the FileExplorer shape so renderers stay agnostic.

createFileExplorerHost function

function createFileExplorerHost(options: ExplorerOptions): Promise<FileExplorerHost>

UtilityProcess-side factory. Loads the native module, owns the EntryStore, walker, and watcher. Import from @vibecook/mille/host.

FileExplorerHost interface

attachPort(port: MessagePortLike): Disposable

Each port is an independent session (expansion + viewport + knownIds).

readonly sessionCount: number

Attached client sessions.

readonly local: FileExplorer

In-process access for host-side SCM/indexers. Prefer host.registerDecorationProvider when badges must fan out to port clients.

registerDecorationProvider(provider): Disposable

Host-level decorations store shared by every session.

dispose(): Promise<void>

Tear down host and native resources.

connectFileExplorer function

function connectFileExplorer(port: MessagePortLike, options?: ClientOptions): Promise<FileExplorer>

Renderer-side factory. Reads from a local ViewportMirror; writes round-trip to the host over the wire protocol (v1 frames).

ClientOptions interface

Field	Type	Default
prefetchRows?	number	`200` — tune to virtualizer overscan
mirrorCap?	number	`20_000` — LRU eviction of cold expansions

Decorations & search

Overlays and filename ranking without poisoning the tree version channel.

Decoration interface

Field	Type	Notes
badge?	string	1–2 chars, e.g. `M`, `!`
color?	string	Theme token
tooltip?	string
propagate?	boolean	Roll up to ancestor folders

DecorationProvider interface

Member	Type	Notes
id	string	Stable provider key
onDidChange	(listener) ⇒ Disposable	Emit when specific EntryIds change
provide	(entry) ⇒ Decoration \| null \| Promise	Per-entry overlay

search method

fx.search(query: string, options?: SearchOptions): Promise<SearchHit[]>

Fuzzy match over filenames/paths in the in-memory entry list. Content search is intentionally out of scope for this package.

SearchOptions	Type	Default
limit?	number	`100`
includeIgnored?	boolean
kinds?	EntryKind[]
caseSensitive?	boolean

SearchHit: { entry, score, matchedIndices } — indices into the name for highlighting.

UI — @vibecook/mille-ui

The engine owns structure; this package renders it. Peer: React 19, @tanstack/react-virtual. Radix peers optional for the styled entry.

FileTree component

Virtualized ARIA tree. Pass fx for standalone use (self-wraps provider), or nest inside FileTreeProvider for shared command registry / multi-tree setups.

Prop	Type	Notes
fx?	FileTreeEngine	Explorer or port client
ariaLabel	string	Required for accessibility
rowHeight?	number	Default `22`
overscan?	number	Default `20`
iconTheme?	IconTheme	VS Code File Icon Theme compatible. Prefer `duotoneIconTheme`, `defaultIconTheme`, or `loadMaterialIconTheme()`
emptyState?	ReactNode
loadingState?	ReactNode
ref?	FileTreeRef	Imperative handle (v0.2)

import { FileTree } from '@vibecook/mille-ui';
import { duotoneIconTheme } from '@vibecook/mille-ui/icons/duotone';
import '@vibecook/mille-ui/tokens.css';

<FileTree fx={fx} ariaLabel="Files" rowHeight={22} iconTheme={duotoneIconTheme} />;

FileTreeRef interface

Imperative handle via forwardRef / useFileTreeRef.

revealPath / revealId

Expand ancestors and scroll the target into view.

scrollToRow

Scroll to a visible row index.

clearSelection / clearFilter / clearClipboard

Reset interaction state.

focusFilter

Move focus to the filter input.

UI entry points modules

Import		Contents
@vibecook/mille-ui		Styled FileTree, hooks, decorations UI
…/headless		Structural components + class catalog
…/commands		Command registry + defaults (expand, rename, delete…)
…/git		registerGitDecorations (host-wired client)
…/git/node		createShellGitClient — spawns git status
…/agent-rules		.cursor/rules, CLAUDE.md, .kiro badges
…/icons		Re-exports default + duotone themes
…/icons/default		Monoline folder + file icons
…/icons/duotone		Soft-duotone set (product default)
…/icons/material		Material Icon Theme bundle
…/testing		createFakeEngine for unit tests
…/tokens.css		CSS variables for the styled tree