vfs-kit 1.0.2 → 1.0.3

package/README.md

@@ -1,145 +1,618 @@
-# vfs-kit Explorer — React + TypeScript + Vite
+# vfs-kit
 
-A dual-pane file explorer built on top of `vfs-kit`, demonstrating a fully custom UI layer over a virtual filesystem engine. Features tabbed editing, drag-and-drop file tree, and per-file snapshot history.
+A headless virtual filesystem engine for React. Provides a fully typed adapter model, a caching engine, and a suite of hooks and renderless components for building file explorers, editors, and asset managers — with no opinions on styling.
 
 ---
 
-## Features
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Adapters](#adapters)
+  - [InMemoryAdapter](#inmemoryadapter)
+  - [IndexedDBAdapter](#indexeddbadapter)
+  - [RestAdapter](#restadapter)
+  - [Writing a Custom Adapter](#writing-a-custom-adapter)
+- [Provider](#provider)
+- [Hooks](#hooks)
+  - [useVfs](#usevfs)
+  - [useVfsEngine](#usevfsengine)
+  - [useVfsTabs](#usevfstabs)
+  - [useVfsHistory](#usevfshistory)
+  - [useVfsExpanded](#usevfsexpanded)
+  - [useVfsSelection](#usevfsselection)
+  - [useSortableTab](#usesoratabletab)
+- [Components](#components)
+  - [FileTree](#filetree)
+  - [FileRenderer](#filerenderer)
+  - [TabList / TabListBase](#tablist--tablistbase)
+  - [InlineInput](#inlineinput)
+- [Core Types](#core-types)
+- [Roadmap](#roadmap)
 
-- **Dual-pane layout** — two independent `FilePane` instances (`Source` / `Target`), each with its own workspace, file tree, and tab strip
-- **Custom file tree** — built with `FileTree` + a fully custom `renderNode` prop; supports drag-and-drop reordering, inline rename (`InlineInput`), folder expand/collapse, and drop-zone overlays
-- **Tabbed editor** — uses `TabListBase` (not `TabList`) so tabs share a single `useVfsTabs` instance with the rest of the pane; tabs support dirty indicators, lock/unlock, drag-to-reorder, and close
-- **Per-file snapshot history** — `useFileHistory` hook manages snapshots per open file using only the public `fs` / `tree` surfaces from `useVfsEngine`; the `HistoryPanel` sidebar lets you label, take, restore, and remove snapshots
-- **Clean tab switching** — `Editor` is keyed on `node.id` so React fully remounts it on tab change, resetting both content state and history without any manual sync
+---
+
+## Installation
+
+```bash
+npm install vfs-kit
+```
+
+Peer dependencies: `react`, `react-dom`, `@dnd-kit/core`, `@dnd-kit/sortable`, `@dnd-kit/utilities`.
+
+For `IndexedDBAdapter`: `idb`.
 
 ---
 
-## Architecture
+## Quick Start
+
+```tsx
+import { VfsProvider } from 'vfs-kit';
+import { InMemoryAdapter } from 'vfs-kit/adapters';
+import { FileTree } from 'vfs-kit/components';
+import { useVfsEngine } from 'vfs-kit/hooks';
+
+const adapter = new InMemoryAdapter();
+
+export default function App() {
+    return (
+        <VfsProvider
+            workspaces={[{ id: 'main', name: 'My Files', adapter }]}
+            config={{ sessionId: 'user-1' }}
+        >
+            <Explorer />
+        </VfsProvider>
+    );
+}
+
+function Explorer() {
+    const { fs } = useVfsEngine('main');
+
+    return (
+        <FileTree
+            workspaceId="main"
+            renderNode={({ flatNode, onClick, dragHandleProps, style }) => (
+                <div {...dragHandleProps} onClick={onClick} style={style}>
+                    {flatNode.node.name}
+                </div>
+            )}
+        />
+    );
+}
+```
+
+---
 
-### `FilePane`
+## Adapters
 
-The top-level pane component. Owns the single `useVfsTabs` instance for its workspace and passes it directly into `TabListBase` — this is important because `TabList` (the higher-level component) would create its own internal `useVfsTabs` instance, resulting in two disconnected reducer states.
+Adapters implement the `VfsAdapter` abstract class and provide the storage backend. Three are included; you can write your own.
 
+### InMemoryAdapter
+
+Stores everything in `Map`s. No setup required. Ideal for prototyping, testing, and ephemeral state.
+
+```ts
+import { InMemoryAdapter } from 'vfs-kit/adapters';
+
+const adapter = new InMemoryAdapter();
 ```
-FilePane
-├── FileTree (sidebar)          ← custom renderNode wired to tabs.open on file click
-├── TabListBase (tab strip)     ← driven by the same tabs instance as FileTree
-└── FileRenderer (editor area)
-    └── Editor (keyed on node.id)
-        ├── textarea
-        ├── useFileHistory
-        └── HistoryPanel
+
+Supports history (`supportsHistory = true`). Data is lost on page refresh.
+
+You can pre-seed the adapter directly before passing it to `VfsProvider`:
+
+```ts
+const root = await adapter.createFolder({ parentId: null, name: 'src' });
+const file = await adapter.createFile({ parentId: root.id, name: 'index.ts', mimeType: 'text/typescript' });
+await adapter.writeFile(file.id, new TextEncoder().encode('export {}'));
 ```
 
-### `useFileHistory`
+### IndexedDBAdapter
 
-Per-tab in-memory snapshot manager. Scoped to the currently open file — history is intentionally discarded when the tab closes.
+Persists to the browser's IndexedDB via [`idb`](https://github.com/jakearchibald/idb). Survives page refresh. Supports optional cross-tab sync via `BroadcastChannel`.
 
 ```ts
-const { snapshots, takeSnapshot, restore, remove, loading } = useFileHistory({
-    workspaceId: 'ws-a',
-    nodeId:      'some-file-id',
-    onRestore:   (bytes) => setContent(new TextDecoder().decode(bytes)),
+import { IndexedDBAdapter } from 'vfs-kit/adapters';
+
+const adapter = new IndexedDBAdapter({
+    dbName:    'my-app-fs',
+    dbVersion: 1,              // optional, default 1
+    isolation: 'shared',       // 'private' (default) | 'shared' — enables BroadcastChannel sync
 });
-```
 
-- `takeSnapshot(label?)` — calls `fs.snapshot`, then re-fetches via `tree.getSnapshots` to update the list immediately
-- `restore(index)` — fetches snapshot content, writes it back via `fs.write`, then calls `onRestore` so the editor syncs its controlled state
-- `remove(index)` — local-state removal only; `deleteSnapshot` is not yet a formal `VfsCommand` (see [Roadmap](#roadmap))
+await adapter.open(); // must be called before passing to VfsProvider
+```
 
-Uses only the public `fs` / `tree` surfaces — no direct `engine` access.
+Call `adapter.close()` on unmount if managing lifecycle manually.
 
-### `Editor`
+Supports history (`supportsHistory = true`). Enforces a 50-snapshot cap per file, evicting the oldest automatically.
 
-Extracted from `FilePane` and keyed on `node.id`. Owns its own `content` state initialised from `initialContent`, and delegates history entirely to `useFileHistory`. The `setContentRef` pattern ensures `onRestore` never captures a stale setter across re-renders.
+### RestAdapter
 
-### `HistoryPanel`
+Delegates all operations to a remote HTTP API. Connects to a server-sent events (SSE) endpoint for real-time change propagation, with an optional fallback for non-SSE environments.
 
-Collapsible sidebar rendered inside `Editor`. Shows snapshots most-recent first with timestamp and byte size. Each entry has restore (↺) and delete (🗑) actions. The label input submits on Enter or the `+` button.
+```ts
+import { RestAdapter } from 'vfs-kit/adapters';
+
+const adapter = new RestAdapter({
+    baseUrl:          'https://api.example.com/fs',
+    supportsHistory:  true,       // default true
+    fetch:            customFetch, // optional — defaults to globalThis.fetch
+    endpoints:        { ... },    // optional — override individual endpoint URLs
+    realtimeFallback: (onMessage, onError) => {
+        // e.g. set up a WebSocket and return a cleanup function
+        return () => { /* disconnect */ };
+    },
+});
 
----
+await adapter.open();
+```
 
-## Key Implementation Notes
+**Default endpoint conventions** (all relative to `baseUrl`):
 
-### Why `TabListBase` instead of `TabList`
+| Operation | Method | Path |
+|---|---|---|
+| Get node | GET | `/nodes/:id` |
+| Get children | GET | `/nodes/:parentId/children` |
+| Create file | POST | `/nodes/file` |
+| Create folder | POST | `/nodes/folder` |
+| Write content | PUT | `/content/:id` |
+| Move (batch) | POST | `/nodes/batch/move` |
+| Get snapshots | GET | `/snapshots/:fileId` |
+| Save snapshot | POST | `/snapshots/:fileId` |
+| Restore snapshot | POST | `/snapshots/:fileId/:index/restore` |
+| Delete snapshot | DELETE | `/snapshots/:fileId/:index` |
+| SSE stream | GET | `/events` |
 
-`TabList` calls `useVfsTabs` internally, producing a second isolated reducer. `TabListBase` accepts the tab state as props, so the single instance created in `FilePane` is the source of truth for both the tree's `tabs.open()` calls and the tab strip's render.
+Any endpoint can be overridden individually via the `endpoints` option.
 
-### Why `Editor` is keyed on `node.id`
+### Writing a Custom Adapter
 
-Without a key, switching tabs leaves the previous file's content in state. Keying causes React to fully unmount and remount `Editor`, which resets `content`, `snapshots`, and `loading` cleanly — no `useEffect` sync required.
+Extend `VfsAdapter` and implement all abstract methods. Set `supportsHistory = true` and implement the four history methods (`getSnapshots`, `saveSnapshot`, `restoreSnapshot`, `deleteSnapshot`) if your backend supports it.
 
-### Why `tree` is omitted from `useEffect` deps in `useFileHistory`
+```ts
+import { VfsAdapter } from 'vfs-kit/core';
 
-`useVfsEngine` builds `tree` via an immediately-invoked `useCallback` (`useCallback(...)()`) so a new object reference is produced on every render. Including it in deps would cause an infinite reload loop. `nodeId` is the correct and only trigger.
+export class MyAdapter extends VfsAdapter {
+    readonly supportsHistory = false;
+    // implement abstract methods...
+}
+```
 
 ---
 
-## Roadmap
+## Provider
+
+`VfsProvider` initialises the engine for each workspace and makes them available via context.
+
+```tsx
+<VfsProvider
+    workspaces={[
+        { id: 'ws-a', name: 'Source', adapter: adapterA },
+        { id: 'ws-b', name: 'Target', adapter: adapterB },
+    ]}
+    config={{
+        sessionId:           'user-123',      // required — used for node locking
+        allowDuplicateNames: false,           // default false
+        duplicateResolution: 'throw',         // 'throw' | 'rename' — default 'throw'
+        history: {
+            maxSnapshots: 50,                 // default 50
+            autosave: {
+                enabled:    false,            // default false
+                intervalMs: 30_000,
+            },
+        },
+    }}
+    cacheStrategy="hybrid"                    // 'eager' | 'lazy' | 'hybrid' — default 'hybrid'
+    tabPersistence={{ strategy: 'session' }}  // 'session' | 'none' — default 'none'
+    fallback={<div>Loading…</div>}
+>
+    {children}
+</VfsProvider>
+```
 
-- **`deleteSnapshot` as a formal command** — add `{ op: 'deleteSnapshot', fileId, index }` to `VfsCommand` in `VfsEngine`, wire it through `runSnapshot`, expose it on `VfsFsApi` as `fs.deleteSnapshot(fileId, index)`, then replace the local-only removal in `useFileHistory.remove` with that call
-- **Autosave snapshots** — `VfsEngineConfig` already has `history.autosave` — hook up a `setInterval` in `useFileHistory` when `autosave.enabled` is true
-- **Snapshot diff view** — compare snapshot content against current file content before restoring
+**Cache strategies:**
+- `eager` — loads all nodes on init
+- `lazy` — loads nodes on demand
+- `hybrid` — loads root children on init, everything else on demand
 
 ---
 
-## Vite / ESLint setup
+## Hooks
 
-This project was scaffolded from the official React + TypeScript + Vite template.
+### useVfs
 
-### Available plugins
+The all-in-one hook. Combines engine, tabs, selection, and expanded state in a single call. Use this when you want everything wired together; use the individual hooks when you need fine-grained control.
 
-- [`@vitejs/plugin-react`](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) — uses Babel (or oxc with rolldown-vite) for Fast Refresh
-- [`@vitejs/plugin-react-swc`](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) — uses SWC for Fast Refresh
+```ts
+import { useVfs } from 'vfs-kit/hooks';
+
+const {
+    fs,        // VfsFsApi   — write operations
+    tree,      // VfsTreeApi — read operations
+    status,    // VfsStatusApi
+    tabs,      // VfsTabsApi
+    selection, // VfsSelectionApi
+    expanded,  // VfsExpandedApi
+} = useVfs({
+    workspaceId: 'ws-a',           // optional — defaults to active workspace
+    tabs:      { workspaceIds: ['ws-a'] },
+    selection: { multiSelect: true, rangeSelect: true },
+    expanded:  { persistKey: 'sidebar-expanded' },
+});
+```
 
-### React Compiler
+### useVfsEngine
 
-Not enabled by default due to dev/build performance impact. See the [React Compiler installation docs](https://react.dev/learn/react-compiler/installation) to add it.
+Returns only the `fs` / `tree` / `status` surfaces for a workspace. The most commonly used hook when you don't need tabs or selection.
 
-### Type-aware ESLint rules
+```ts
+const { fs, tree, status } = useVfsEngine('ws-a');
+```
 
-For production apps, enable type-aware lint rules:
+**`fs` — write operations:**
 
-```js
-export default defineConfig([
-  globalIgnores(['dist']),
-  {
-    files: ['**/*.{ts,tsx}'],
-    extends: [
-      tseslint.configs.recommendedTypeChecked,
-      // or tseslint.configs.strictTypeChecked for stricter rules
-      tseslint.configs.stylisticTypeChecked,
-    ],
-    languageOptions: {
-      parserOptions: {
-        project: ['./tsconfig.node.json', './tsconfig.app.json'],
-        tsconfigRootDir: import.meta.dirname,
-      },
-    },
-  },
-])
-```
-
-You can also add React-specific lint rules:
-
-```js
-import reactX   from 'eslint-plugin-react-x'
-import reactDom from 'eslint-plugin-react-dom'
-
-export default defineConfig([
-  globalIgnores(['dist']),
-  {
-    files: ['**/*.{ts,tsx}'],
-    extends: [
-      reactX.configs['recommended-typescript'],
-      reactDom.configs.recommended,
-    ],
-    languageOptions: {
-      parserOptions: {
-        project: ['./tsconfig.node.json', './tsconfig.app.json'],
-        tsconfigRootDir: import.meta.dirname,
-      },
+```ts
+fs.createFile(parentId, name, { mimeType?, meta? })
+fs.createFolder(parentId, name, { meta? })
+fs.rename(id, newName)
+fs.delete(ids, permanent?)        // soft-delete by default
+fs.restore(ids)
+fs.purge(ids)                     // permanent delete
+fs.move(ids, newParentId)
+fs.write(id, content)             // Uint8Array
+fs.lock(ids)
+fs.unlock(ids)
+fs.reorder(parentId, orderedIds)
+fs.snapshot(fileId, label?)
+fs.execute(command)               // raw VfsCommand escape hatch
+```
+
+**`tree` — read operations:**
+
+```ts
+tree.getNode(id)                  // Promise<VfsNode | null>
+tree.getChildren(parentId, opts?) // Promise<VfsNode[]>
+tree.getPath(id)                  // Promise<string>  e.g. '/src/index.ts'
+tree.readFile(id)                 // Promise<Uint8Array>
+tree.readJSON<T>(id)              // Promise<T>
+tree.writeJSON<T>(id, data)       // Promise<void>
+tree.search(query, opts?)
+tree.getTrashed()
+tree.getSnapshots(fileId)         // Promise<VfsFileSnapshot[]>
+```
+
+**`status`:**
+
+```ts
+status.pending  // boolean — true while a command is in flight
+status.error    // Error | null — last command error
+status.version  // number — increments on every change, useful as a cache key
+```
+
+### useVfsTabs
+
+Manages open file tabs. Supports dirty tracking, locking, drag-to-reorder, and optional session persistence.
+
+```ts
+import { useVfsTabs } from 'vfs-kit/hooks';
+
+const tabs = useVfsTabs({
+    workspaceIds: ['ws-a'],     // optional
+    dirtyChecker: ({ savedContent, currentContent }) => ..., // optional custom checker
+});
+```
+
+```ts
+tabs.tabs           // VfsTab[]
+tabs.activeTabId    // string | null
+tabs.activeTab      // VfsTab | null
+
+tabs.open(nodeId, workspaceId)   // opens or focuses a tab
+tabs.close(tabId)
+tabs.closeOthers(tabId)
+tabs.closeAll(workspaceId?)
+tabs.setActive(tabId)
+tabs.reorder(activeId, overId)
+tabs.lock(tabId)
+tabs.unlock(tabId)
+tabs.markDirty(tabId, currentContent)
+tabs.markSaved(tabId)
+```
+
+**`VfsTab` shape:**
+
+```ts
+interface VfsTab {
+    id:             string;
+    nodeId:         string;
+    workspaceId:    string;
+    title:          string;
+    isDirty:        boolean;
+    isLocked:       boolean;
+    savedContent:   Uint8Array | null;
+    currentContent: Uint8Array | null;
+    lastSavedAt:    number | null;
+}
+```
+
+> **Important:** when using a custom tab UI, use `TabListBase` and pass your `useVfsTabs` instance into it directly. Using `TabList` creates its own internal `useVfsTabs` instance which will be disconnected from yours.
+
+### useVfsHistory
+
+Per-file snapshot manager. Loads snapshots for the active file and keeps the list up to date as snapshots are taken. Scoped to the current render — history is discarded when the component unmounts.
+
+```ts
+import { useVfsHistory } from 'vfs-kit/hooks';
+
+const { snapshots, takeSnapshot, restore, remove, loading } = useVfsHistory({
+    workspaceId: 'ws-a',
+    nodeId:      'file-id',           // null clears the list
+    onRestore:   (bytes) => {         // called after a restore so you can sync editor state
+        setContent(new TextDecoder().decode(bytes));
     },
-  },
-])
-```
+});
+```
+
+```ts
+takeSnapshot(label?)     // saves current file content as a new snapshot
+restore(index)           // writes snapshot content back to the file and calls onRestore
+remove(index)            // removes a snapshot
+loading                  // true while the initial snapshot list is loading
+snapshots                // VfsFileSnapshot[] — most-recent first
+```
+
+**`VfsFileSnapshot` shape:**
+
+```ts
+interface VfsFileSnapshot {
+    id:        string;
+    fileId:    string;
+    index:     number;
+    content:   Uint8Array;
+    createdAt: number;
+    label?:    string;
+}
+```
+
+Only available when the adapter has `supportsHistory = true` (`InMemoryAdapter` and `IndexedDBAdapter` both do; `RestAdapter` depends on your server).
+
+### useVfsExpanded
+
+Manages folder expanded state in a file tree. Persists to `sessionStorage` when a `persistKey` is provided. Automatically collapses deleted folders.
+
+```ts
+const expanded = useVfsExpanded({
+    workspaceIds:   ['ws-a'],            // optional
+    defaultExpanded: ['folder-id'],      // optional
+    persistKey:      'sidebar-expanded', // optional — enables sessionStorage persistence
+});
+```
+
+```ts
+expanded.expandedIds          // Set<string>
+expanded.isExpanded(id)       // boolean
+expanded.expand(id)
+expanded.collapse(id)
+expanded.toggle(id)
+expanded.expandAll(ids)
+expanded.collapseAll()
+expanded.expandToNode(id, workspaceId?)  // expands all ancestors of a node
+```
+
+### useVfsSelection
+
+Manages selected node state. Supports single select, multi-select, and shift-range select.
+
+```ts
+const selection = useVfsSelection({
+    multiSelect: true,  // default true
+    rangeSelect: true,  // default true
+});
+```
+
+```ts
+selection.selection       // string[]
+selection.lastSelectedId  // string | null
+selection.isSelected(id)  // boolean
+selection.select(id)      // replaces selection
+selection.toggle(id)      // adds/removes from selection
+selection.selectRange(orderedIds, anchorId, targetId)
+selection.deselect(id)
+selection.deselectAll()
+selection.selectAll(ids)
+```
+
+### useSortableTab
+
+A thin wrapper around `@dnd-kit/sortable`'s `useSortable` for tab drag-to-reorder. Returns `ref`, `style`, and `dragHandleProps` ready to spread onto a tab element.
+
+```ts
+import { useSortableTab } from 'vfs-kit/hooks';
+
+function MyTab({ tab }) {
+    const { ref, style, dragHandleProps } = useSortableTab(tab.id);
+    return (
+        <div ref={ref} style={style} {...dragHandleProps}>
+            {tab.title}
+        </div>
+    );
+}
+```
+
+Used internally by `TabListBase` when `sortable` is true. Use it directly when building a fully custom tab strip.
+
+---
+
+## Components
+
+All components are headless by default — they manage behaviour and delegate rendering to your own render props.
+
+### FileTree
+
+Renders a flat virtualised list of nodes for a workspace. Handles expand/collapse, drag-and-drop reordering, inline creation, and drop-zone overlays.
+
+```tsx
+import { FileTree } from 'vfs-kit/components';
+
+<FileTree
+    workspaceId="ws-a"
+    draggable                         // enables drag-and-drop
+    renderNode={({ flatNode, isSelected, isActive, isDragging, isDragSession,
+                   isRenaming, setRenaming, dragHandleProps, style, onClick }) => (
+        <div {...dragHandleProps} onClick={onClick} style={style}>
+            {flatNode.node.name}
+        </div>
+    )}
+    inlineCreate={{ kind: 'file' }}   // pass null to cancel
+    onCancelCreate={() => {}}
+    folderOverlay={{
+        mode: 'full',                 // 'full' | 'none'
+        renderOverlay: ({ isBlocked, isEmpty }) => <div />,
+    }}
+/>
+```
+
+**`NodeRenderProps`:**
+
+```ts
+interface NodeRenderProps<TMeta> {
+    flatNode:        FlatNode<TMeta>;  // { node, level, isOpen }
+    isSelected:      boolean;
+    isActive:        boolean;
+    isDragging:      boolean;
+    isDragSession:   boolean;
+    isRenaming:      boolean;
+    setRenaming:     (v: boolean) => void;
+    dragHandleProps: Record<string, unknown>;
+    style:           React.CSSProperties;
+    onClick:         (e: React.MouseEvent) => void;
+}
+```
+
+> When a file node is clicked, `FileTree`'s internal `onClick` handles selection and expand — it does not open tabs. Wire `tabs.open(node.id, workspaceId)` inside your `renderNode` click handler if you want tab behaviour.
+
+### FileRenderer
+
+Loads and renders the content of the active file. Re-runs when `activeNodeId` changes, handles loading and error states, and calls `onLoad` once content is available.
+
+```tsx
+import { FileRenderer } from 'vfs-kit/components';
+
+<FileRenderer
+    workspaceId="ws-a"
+    activeNodeId={tabs.activeTab?.nodeId ?? null}
+    onLoad={(node, bytes) => setContent(new TextDecoder().decode(bytes))}
+    onError={(node, error) => console.error(error)}
+    fallback={<div>No file open</div>}
+>
+    {({ node, content, loading, error }) => (
+        <textarea value={new TextDecoder().decode(content ?? new Uint8Array())} />
+    )}
+</FileRenderer>
+```
+
+> Key the child component on `node.id` if it owns its own content state — this causes React to fully remount on tab switch, cleanly resetting state without a `useEffect`.
+
+### TabList / TabListBase
+
+`TabList` is the higher-level component: it creates its own `useVfsTabs` instance internally.
+
+`TabListBase` is the lower-level component: it accepts tab state as props, so you can drive it from a `useVfsTabs` instance you control elsewhere. **Use `TabListBase` when you are also calling `tabs.open()` from your own code** — otherwise the tab strip and your open calls will be in two disconnected states.
+
+```tsx
+import { TabListBase } from 'vfs-kit/components';
+
+// tabs = useVfsTabs({ workspaceIds: ['ws-a'] })
+
+<TabListBase
+    tabs={tabs.tabs}
+    activeTabId={tabs.activeTabId}
+    onReorder={tabs.reorder}
+    onClose={tabs.close}
+    onSetActive={tabs.setActive}
+    onLock={tabs.lock}
+    onUnlock={tabs.unlock}
+    sortable                          // enables drag-to-reorder via @dnd-kit
+>
+    {({ tabs: tabList, activeTabId, onClose, onSetActive, onLock, onUnlock, dragHandleProps }) => (
+        <div style={{ display: 'flex' }}>
+            {tabList.map(tab => (
+                <MyTab
+                    key={tab.id}
+                    tab={tab}
+                    isActive={tab.id === activeTabId}
+                    dragHandleProps={dragHandleProps(tab.id)}
+                    onSetActive={onSetActive}
+                    onClose={onClose}
+                    onLock={onLock}
+                    onUnlock={onUnlock}
+                />
+            ))}
+        </div>
+    )}
+</TabListBase>
+```
+
+### InlineInput
+
+A controlled text input designed for inline rename flows. Commits on Enter or blur, cancels on Escape.
+
+```tsx
+import { InlineInput } from 'vfs-kit/components';
+
+<InlineInput
+    initialValue={node.name}
+    onSubmit={(newName) => fs.rename(node.id, newName)}
+    onCancel={() => setRenaming(false)}
+    className="my-input-class"
+/>
+```
+
+---
+
+## Core Types
+
+```ts
+// vfs-kit/core
+
+interface VfsNode<TMeta> {
+    id:        string;
+    name:      string;
+    kind:      'file' | 'folder';
+    parentId:  string | null;
+    sortIndex: number | null;
+    lockedBy:  string | null;
+    createdAt: number;
+    updatedAt: number;
+    deletedAt: number | null;
+    meta:      TMeta;
+}
+
+interface VfsFileNode<TMeta> extends VfsNode<TMeta> {
+    kind:     'file';
+    mimeType: string;
+    size:     number;
+}
+
+interface VfsFolderNode<TMeta> extends VfsNode<TMeta> {
+    kind: 'folder';
+}
+
+interface VfsFileSnapshot {
+    id:        string;
+    fileId:    string;
+    index:     number;
+    content:   Uint8Array;
+    createdAt: number;
+    label?:    string;
+}
+```
+
+---
+
+## Roadmap
+
+- **`deleteSnapshot` as a formal `VfsCommand`** — currently `remove()` in `useVfsHistory` is local-state only; adding `{ op: 'deleteSnapshot', fileId, index }` to `VfsEngine` and `fs.deleteSnapshot()` to `VfsFsApi` will make it durable
+- **Autosave snapshots** — `VfsEngineConfig.history.autosave` is wired in the config but not yet connected; a `setInterval` in `useVfsHistory` gated on `autosave.enabled` is the planned hookup point
+- **Snapshot diff view** — compare a snapshot's content against the current file before restoring

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vfs-kit",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "A headless-first Virtual File System for React. Complete with drag-and-drop hierarchy, tab management and pluggable storage adapters.",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",