### Get File Tree Composition Settings

Source: https://trees.software/docs

Retrieve the current composition settings for the file tree.

```javascript
getComposition()
```

--------------------------------

### Start Renaming File Tree Item

Source: https://trees.software/docs

Initiate the renaming process for a file tree item, optionally specifying the path to rename.

```javascript
startRenaming(path?)
```

--------------------------------

### Get File Tree Search Value

Source: https://trees.software/docs

Retrieve the current search query string.

```javascript
getSearchValue()
```

--------------------------------

### Get File Tree Search Matching Paths

Source: https://trees.software/docs

Retrieve an array of paths that match the current search query.

```javascript
getSearchMatchingPaths()
```

--------------------------------

### Get File Tree Item Handle

Source: https://trees.software/docs

Retrieve a specific file or directory handle by its path. Returns null if the path does not exist.

```javascript
getItem(path)
```

--------------------------------

### Get Selected File Tree Paths

Source: https://trees.software/docs

Retrieve an array of paths for all currently selected items in the file tree.

```javascript
getSelectedPaths()
```

--------------------------------

### Get Focused File Tree Item

Source: https://trees.software/docs

Retrieve the currently focused item within the file tree.

```javascript
getFocusedItem()
```

--------------------------------

### Get File Tree Container Element

Source: https://trees.software/docs

Retrieve the DOM element that hosts the mounted File Tree runtime after it has been rendered or hydrated.

```javascript
getFileTreeContainer()
```

--------------------------------

### Get Focused File Tree Path

Source: https://trees.software/docs

Retrieve the path of the currently focused item in the file tree.

```javascript
getFocusedPath()
```

--------------------------------

### Select Tree State in React

Source: https://trees.software/docs

Use `useFileTreeSelector` to get custom derived snapshots of the tree state. This hook prevents unnecessary re-renders when unrelated tree changes occur.

```javascript
const selectedPaths = useFileTreeSelector(model, (state) => state.selection.paths);
console.log(selectedPaths);
```

--------------------------------

### Create a FileTree instance

Source: https://trees.software/docs

Instantiate FileTree with raw paths for small trees or preparedInput for scalable trees. The instance serves as the runtime entry point and state surface.

```javascript
new FileTree({ paths, ... })
```

```javascript
new FileTree({ preparedInput, ... })
```

--------------------------------

### Vanilla API - Mounting and Lifecycle

Source: https://trees.software/docs

Covers the methods for mounting, hydrating, unmounting, and cleaning up the FileTree runtime.

```APIDOC
## Mounting and Lifecycle Methods

### Description
Methods to manage the lifecycle of the mounted FileTree runtime.

### Methods
- **render({ fileTreeContainer } | { containerWrapper })**: Mounts the runtime. Accepts either an existing container element or a wrapper for runtime creation.
- **hydrate({ fileTreeContainer })**: Attaches the model to server-rendered tree markup.
- **unmount()**: Removes the mounted runtime while keeping the model available.
- **cleanUp()**: Performs final teardown, including unmounting, subscription cleanup, and model destruction.
- **getFileTreeContainer()**: Returns the mounted host element.
```

--------------------------------

### Instantiate File Tree Vanilla Runtime

Source: https://trees.software/docs

Initialize the File Tree component using the vanilla runtime. Pass shared options to establish the model and expect subsequent updates via model methods.

```javascript
new FileTree(options)
```

--------------------------------

### Vanilla API - FileTree Constructor

Source: https://trees.software/docs

Documentation for the `FileTree` constructor, which initializes the imperative model.

```APIDOC
## new FileTree(options)

### Description
Initializes the imperative model for the file tree. Accepts shared options and establishes the model. Subsequent updates should be made through model methods rather than rebuilding option objects.

### Parameters
- **options**: An object containing shared configuration options for the file tree.
```

--------------------------------

### Create React File Tree Model

Source: https://trees.software/docs

Use `useFileTree` from `@pierre/trees/react` to create the tree model. For small trees, raw `paths` can be used, but for scalability, `preparedInput` is recommended.

```javascript
const model = useFileTree({
  paths: {
    "src/index.ts": { lastModified: 1670000000000, size: 100 },
    "src/components/Button.tsx": { lastModified: 1670000000000, size: 200 },
  },
});
```

```javascript
const model = useFileTree({
  preparedInput: preparePresortedFileTreeInput({
    paths: {
      "src/index.ts": { lastModified: 1670000000000, size: 100 },
      "src/components/Button.tsx": { lastModified: 1670000000000, size: 200 },
    },
  }),
});
```

--------------------------------

### React Handoff: Initialize and Render File Tree

Source: https://trees.software/docs

In React, create the model with `useFileTree(...)`, then pass the SSR payload to the `<FileTree>` component via the `preloadedData` prop.

```javascript
const model = useFileTree(options);
<FileTree model={model} preloadedData={payload} />
```

--------------------------------

### Vanilla Handoff

Source: https://trees.software/docs

How to handle server-rendered data in a vanilla JavaScript application.

```APIDOC
## Vanilla Handoff

### Description
Vanilla emits the server-rendered tree into the page first, creates `new FileTree(options)` on the client, then calls `fileTree.hydrate({ fileTreeContainer })` against the existing host. For the full runtime surface, read Vanilla API. For the workflow guide, read SSR.

### Usage
- `new FileTree(options)`
- `fileTree.hydrate({ fileTreeContainer })`
```

--------------------------------

### Vanilla JavaScript Handoff: Hydrate File Tree

Source: https://trees.software/docs

For Vanilla JavaScript, emit the server-rendered tree into the page, create a `FileTree` instance on the client, and then call `hydrate({ fileTreeContainer })` against the existing host element.

```javascript
const fileTree = new FileTree(options);
fileTree.hydrate({ fileTreeContainer });
```

--------------------------------

### Prepare file tree input on the server

Source: https://trees.software/docs

Use `prepareFileTreeInput` to shape tree data before it reaches the UI, especially for large datasets. This preparation is best done on the server or a non-UI boundary.

```javascript
prepareFileTreeInput(...)
```

--------------------------------

### Vanilla API - Write and Control APIs

Source: https://trees.software/docs

Covers methods for controlling focus, selection, search, data mutations, and runtime reconfiguration.

```APIDOC
## Write and Control APIs

### Description
APIs for manipulating the state and behavior of the file tree.

### Focus and Selection Control
- **focusPath(path)**: Sets focus to the item at the specified path.
- **focusNearestPath(path | null)**: Focuses the nearest item to the given path.
- **scrollToPath(path, { offset?, focus? })**: Scrolls to a specific path. `offset` can be 'top', 'center', or 'nearest'. `focus` (boolean) determines if DOM focus should also move (defaults to true).
- **startRenaming(path?)**: Initiates renaming for an item.
- **Item handle selection and focus methods**: Direct manipulation via item handles.

### Search Control
- **setSearch(value)**: Sets the search query value.
- **openSearch(initialValue?)**: Opens the search interface with an optional initial value.
- **closeSearch()**: Closes the search interface.
- **focusNextSearchMatch()**: Moves focus to the next search result.
- **focusPreviousSearchMatch()**: Moves focus to the previous search result.

### Data and Mutation Control
- **add(path)**: Adds a new item at the specified path.
- **remove(path, options?)**: Removes an item. Options may be provided.
- **move(fromPath, toPath, options?)**: Moves an item from one path to another. Options may be provided.
- **batch(operations)**: Executes a batch of mutation operations.
- **resetPaths(paths, options?)**: Resets the state for the specified paths. Options may be provided.
- **onMutation(type, handler)**: Registers a callback for mutation events.

### Runtime Reconfiguration Helpers
- **setComposition(composition?)**: Sets the composition configuration.
- **setGitStatus(gitStatus?)**: Sets the Git status information.
- **setIcons(icons?)**: Sets custom icons for the tree.
```

--------------------------------

### Vanilla API - Item Handles

Source: https://trees.software/docs

Details the actions available on item handles returned by `getItem(path)`.

```APIDOC
## Item Handles

### Description
Represents individual files or directories within the tree, providing methods for interaction.

### Shared Actions
- **getPath()**: Returns the path of the item.
- **focus()**: Sets focus to this item.
- **select()**: Selects this item.
- **toggleSelect()**: Toggles the selection state of this item.
- **deselect()**: Deselects this item.

### Directory-only Actions
- **expand()**: Expands the directory.
- **collapse()**: Collapses the directory.
- **toggle()**: Toggles the expanded state of the directory.
```

--------------------------------

### React Handoff

Source: https://trees.software/docs

How to handle server-rendered data in a React application.

```APIDOC
## React Handoff

### Description
React creates the model with `useFileTree(...)`, then passes the payload to `<FileTree model={model} preloadedData={payload} />`. For the full runtime surface, read React API. For the workflow guide, read SSR.

### Usage
- `useFileTree(...)
- `<FileTree model={model} preloadedData={payload} />`
```

--------------------------------

### Mutation and Subscriptions from React

Source: https://trees.software/docs

Explains how to use selector hooks for reactive reads and `model.onMutation(...)` for semantic side effects.

```APIDOC
## Mutation and Subscriptions

### Description
Use selector hooks for reactive reads in React UI. Use `model.onMutation(...)` for semantic side effects like persistence, logging, or analytics around mutation operations.

### Method
- **model.onMutation(type, handler)**: Registers a handler for specific mutation types.
```

--------------------------------

### Prepare presorted file tree input

Source: https://trees.software/docs

If the backend or indexer already knows the final order, use `preparePresortedFileTreeInput` to skip client-side sorting and shaping work.

```javascript
preparePresortedFileTreeInput(...)
```

--------------------------------

### Server-Side Rendering: Preload File Tree

Source: https://trees.software/docs

Call `preloadFileTree(options)` on the server to pre-render the tree for the initial paint. It accepts shared `FileTreeOptions` and returns an opaque SSR payload.

```javascript
const payload = await preloadFileTree(options);
// Pass payload to client
```

--------------------------------

### SSR API - preloadFileTree

Source: https://trees.software/docs

Preloads the file tree on the server for initial paint.

```APIDOC
## SSR API - preloadFileTree

### Description
`preloadFileTree(...)` accepts the shared `FileTreeOptions` surface, pre-renders the tree for first paint, and returns an opaque SSR payload. The current exported payload type name is `FileTreeSsrPayload`, but the docs-facing rule stays the same: pass it through unchanged.

### Method
- `preloadFileTree(options)`
```

--------------------------------

### Focus Next File Tree Search Match

Source: https://trees.software/docs

Move focus to the next item that matches the current search query.

```javascript
focusNextSearchMatch()
```

--------------------------------

### Render FileTree into a host element

Source: https://trees.software/docs

Mount the FileTree model into an existing DOM element using `fileTreeContainer`. Alternatively, use `containerWrapper` if the runtime should create the host element.

```javascript
render({ fileTreeContainer })
```

```javascript
render({ containerWrapper })
```

--------------------------------

### Vanilla API - Read APIs

Source: https://trees.software/docs

Lists the common read methods available on the FileTree model for querying its state.

```APIDOC
## Read APIs

### Description
Common methods for reading the state of the file tree model.

### Methods
- **getItem(path)**: Retrieves an item (file or directory) by its path.
- **getFocusedItem()**: Gets the currently focused item.
- **getFocusedPath()**: Gets the path of the currently focused item.
- **getSelectedPaths()**: Gets an array of paths for all selected items.
- **getComposition()**: Retrieves the current composition state.
- **isSearchOpen()**: Checks if the search interface is open.
- **getSearchValue()**: Gets the current search input value.
- **getSearchMatchingPaths()**: Gets an array of paths that match the current search query.
```

--------------------------------

### Writing to the Model from React

Source: https://trees.software/docs

Demonstrates how React components can write to the imperative model, covering focus, selection, search, and mutation operations.

```APIDOC
## Writing to the Model

### Description
React writes to the same imperative model methods exposed by the vanilla runtime. This includes focus and selection methods, search operations, and mutation methods.

### Methods
- **Focus and Selection**: Methods on the model or item handles, including `scrollToPath(...)`.
- **Search Control**: `setSearch(...)`, `openSearch(...)`.
- **Mutation**: `add(...)`, `remove(...)`, `move(...)`, `batch(...)`, `resetPaths(...)`.
- **Runtime Reconfiguration**: `setComposition(...)`, `setGitStatus(...)`, `setIcons(...)`.
```

--------------------------------

### Appearance Boundary

Source: https://trees.software/docs

Runtime touchpoints for managing the appearance of the file tree.

```APIDOC
## Appearance Boundary

### Description
This page names the runtime touchpoints such as `getFileTreeContainer()`, `setGitStatus(...)`, and `setIcons(...)`. For styling variables, theme helpers, and `unsafeCSS`, read Styling and theming. For icon remaps and icon-set lookup, read Icons.

### Methods
- `getFileTreeContainer()`
- `setGitStatus(...)
- `setIcons(...)
```

--------------------------------

### Create Vanilla JS File Tree Model

Source: https://trees.software/docs

Instantiate the `FileTree` class for non-React applications or when managing the tree model imperatively. Use `render` or `hydrate` to attach it to the DOM.

```javascript
const model = new FileTree({
  paths: {
    "src/index.ts": { lastModified: 1670000000000, size: 100 },
    "src/components/Button.tsx": { lastModified: 1670000000000, size: 200 },
  },
});
```

--------------------------------

### Composition Surface

Source: https://trees.software/docs

APIs for composing UI elements like headers and context menus, and for runtime updates.

```APIDOC
## Composition Surface

### Description
The composition surface covers header composition, context-menu composition, and runtime updates through `setComposition(...)`. Use Rename, drag, and trigger item actions for workflow-level guidance.

### Methods
- `setComposition(...)
```

--------------------------------

### File Tree Item Handle Actions

Source: https://trees.software/docs

Common actions available on file and directory item handles, including path retrieval, focus, selection, and deselection.

```javascript
getPath()
```

```javascript
focus()
```

```javascript
select()
```

```javascript
toggleSelect()
```

```javascript
deselect()
```

--------------------------------

### Open File Tree Search

Source: https://trees.software/docs

Open the search interface, optionally with an initial search value.

```javascript
openSearch(initialValue?)
```

--------------------------------

### Focus Previous File Tree Search Match

Source: https://trees.software/docs

Move focus to the previous item that matches the current search query.

```javascript
focusPreviousSearchMatch()
```

--------------------------------

### Set File Tree Icons

Source: https://trees.software/docs

Configure custom icons to be used for different file types or states within the file tree.

```javascript
setIcons(icons?)
```

--------------------------------

### Hydration Boundary

Source: https://trees.software/docs

The vanilla hydration entry point for the tree.

```APIDOC
## Hydration Boundary

### Description
This page only names the vanilla hydration entry point: `hydrate({ fileTreeContainer })`. The full server-preload-first contract lives in SSR API.

### Method
- `hydrate({ fileTreeContainer })`
```

--------------------------------

### Use File Tree Search Hook

Source: https://trees.software/docs

Provides the current search snapshot, including open state and matching paths, along with model-backed actions to control the search interface.

```typescript
useFileTreeSearch(model)
```

--------------------------------

### Subscriptions

Source: https://trees.software/docs

Methods for subscribing to tree changes and mutation events.

```APIDOC
## Subscriptions

### Description
Use `subscribe(listener)` to refresh a derived snapshot when any tree change occurs. Use `onMutation(...)` when add, remove, move, reset, or batch intent matters. This separation keeps model subscriptions for state reads and mutation events for semantic side effects.

### Methods
- `subscribe(listener)`
- `onMutation(...)
```

--------------------------------

### Hydrate FileTree with SSR output

Source: https://trees.software/docs

Attach a FileTree model to server-rendered tree output using `hydrate` for SSR scenarios. The client still creates the FileTree instance.

```javascript
hydrate({ fileTreeContainer })
```

--------------------------------

### Scroll to File Tree Path

Source: https://trees.software/docs

Scroll the virtualizer to reveal a specific path. Optionally control the scroll offset and whether to move DOM focus.

```javascript
scrollToPath(path, { offset: 'top' | 'center' | 'nearest', focus?: boolean })
```

--------------------------------

### Set File Tree Composition

Source: https://trees.software/docs

Configure the composition settings for the file tree, affecting its appearance or behavior.

```javascript
setComposition(composition?)
```

--------------------------------

### Focus Nearest File Tree Path

Source: https://trees.software/docs

Set the focus to the nearest available path, or clear focus if null is provided.

```javascript
focusNearestPath(path | null)
```

--------------------------------

### Focus File Tree Path

Source: https://trees.software/docs

Set the focus to a specific item identified by its path.

```javascript
focusPath(path)
```

--------------------------------

### Add Item to File Tree

Source: https://trees.software/docs

Add a new item to the file tree at the specified path.

```javascript
add(path)
```

--------------------------------

### Use File Tree Selection Hook

Source: https://trees.software/docs

A convenience hook for accessing the array of selected paths in a read-only manner.

```typescript
useFileTreeSelection(model)
```

--------------------------------

### Render React File Tree Component

Source: https://trees.software/docs

The `<FileTree />` component is a thin React wrapper that mounts the tree model into a host element. It forwards standard host props and supports SSR hydration via `preloadedData`.

```javascript
<FileTree model={model} className="my-tree" />
```

--------------------------------

### React Hooks for File Tree Interaction

Source: https://trees.software/docs

These hooks provide a declarative way to interact with the file tree model from React components, enabling reactive reads and state selection.

```APIDOC
## useFileTreeSelector(model, selector, equality?)

### Description
Provides a generic bridge from the imperative model into React, returning a selected snapshot from the current model. Accepts an optional equality function for custom value comparison.

### Parameters
- **model**: The file tree model instance.
- **selector**: A function that selects a portion of the model state.
- **equality** (optional): A function to compare selected values.
```

```APIDOC
## useFileTreeSelection(model)

### Description
A convenience hook that returns the `readonly string[]` of selected paths from the file tree model.

### Parameters
- **model**: The file tree model instance.
```

```APIDOC
## useFileTreeSearch(model)

### Description
Returns the current search snapshot along with model-backed actions for controlling search functionality. The snapshot includes `isOpen`, `matchingPaths`, and `value`.

### Parameters
- **model**: The file tree model instance.

### Actions
- **open(initialValue?)**: Opens the search interface.
- **close()**: Closes the search interface.
- **setValue(value)**: Sets the search input value.
- **focusNextMatch()**: Moves focus to the next search match.
- **focusPreviousMatch()**: Moves focus to the previous search match.
```

--------------------------------

### Batch Operations on File Tree

Source: https://trees.software/docs

Perform multiple mutation operations (add, remove, move, etc.) on the file tree in a single batch for efficiency.

```javascript
batch(operations)
```

--------------------------------

### SSR API - serializeFileTreeSsrPayload

Source: https://trees.software/docs

Serializes the preloaded SSR payload into a host-markup string.

```APIDOC
## SSR API - serializeFileTreeSsrPayload

### Description
`serializeFileTreeSsrPayload(payload, mode?)` turns the preloaded payload back into a full host-markup string. Use it when your server integration needs a serialized HTML string instead of passing the payload through a framework-specific render boundary. The payload still stays opaque at the docs level.

### Method
- `serializeFileTreeSsrPayload(payload, mode?)
```

--------------------------------

### Reset Paths in File Tree

Source: https://trees.software/docs

Reset the state of specified paths within the file tree. Optional configuration can be provided.

```javascript
resetPaths(paths, options?)
```

--------------------------------

### Move Item in File Tree

Source: https://trees.software/docs

Move an item from a source path to a destination path within the file tree. Optional configuration can be provided.

```javascript
move(fromPath, toPath, options?)
```

--------------------------------

### Clean Up File Tree Resources

Source: https://trees.software/docs

Perform a final teardown of the File Tree component, including unmounting the runtime, cleaning up subscriptions, and destroying the model.

```javascript
cleanUp()
```

--------------------------------

### Server-Side Rendering: Serialize File Tree Payload

Source: https://trees.software/docs

Use `serializeFileTreeSsrPayload(payload, mode?)` to convert the preloaded SSR payload into a full host-markup string. This is useful when your server integration requires HTML output.

```javascript
const htmlString = serializeFileTreeSsrPayload(payload);
// Use htmlString in server response
```

--------------------------------

### Subscribe to File Tree Mutations

Source: https://trees.software/docs

Register a handler function to be called for specific mutation types (add, remove, move, reset, batch) to perform side effects like logging or persistence.

```javascript
onMutation(type, handler)
```

--------------------------------

### React-Specific Composition Surface

Source: https://trees.software/docs

Details the high-level composition props added by React for custom header and context menu rendering.

```APIDOC
## React Composition Props

### Description
React adds two high-level composition props on top of the model for custom UI elements.

### Props
- **header**: For React-rendered header content.
- **renderContextMenu(item, context)**: For React-rendered context menus.
```

--------------------------------

### Update FileTree state imperatively

Source: https://trees.software/docs

When surrounding data changes, use explicit model methods like `resetPaths`, `setComposition`, `setGitStatus`, or `setIcons` to update the tree state.

```javascript
resetPaths(...)
```

```javascript
setComposition(...)
```

```javascript
setGitStatus(...)
```

```javascript
setIcons(...)
```

--------------------------------

### Directory-Specific Item Handle Actions

Source: https://trees.software/docs

Actions exclusive to directory item handles, allowing for expansion, collapse, and toggling of directory nodes.

```javascript
expand()
```

```javascript
collapse()
```

```javascript
toggle()
```

--------------------------------

### Check if File Tree Search is Open

Source: https://trees.software/docs

Determine whether the search interface is currently open.

```javascript
isSearchOpen()
```

--------------------------------

### Set File Tree Search Value

Source: https://trees.software/docs

Update the search query and trigger a search operation.

```javascript
setSearch(value)
```

--------------------------------

### Use File Tree Selector Hook

Source: https://trees.software/docs

Use this hook for imperative model access within React. It returns a snapshot of the current model state and accepts an optional equality function for custom comparisons.

```typescript
useFileTreeSelector(model, selector, equality?)
```

--------------------------------

### Remove Item from File Tree

Source: https://trees.software/docs

Remove an item from the file tree at the specified path. Optional configuration can be provided.

```javascript
remove(path, options?)
```

--------------------------------

### Unmount File Tree Component

Source: https://trees.software/docs

Remove the mounted File Tree runtime from the DOM while preserving the underlying model instance for potential re-attachment.

```javascript
unmount()
```

--------------------------------

### Set File Tree Git Status

Source: https://trees.software/docs

Update the Git status indicators for items within the file tree.

```javascript
setGitStatus(gitStatus?)
```

--------------------------------

### Close File Tree Search

Source: https://trees.software/docs

Close the search interface.

```javascript
closeSearch()
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.