<!-- source-hash: 8886b4928afb072c5436308281384b36 -->
Pure navigation helpers for traversing and resolving paths within a `DocNode` tree — shared between client-side hooks and server-side RSC rendering.

## Key Components

| Export | Type | Description |
|---|---|---|
| `DEFAULT_FOLDER_INDEX_FILE` | `const` | Canonical folder-index filename (`'README.md'`); single source of truth across navigation, SEO, and fetch logic |
| `stripFolderIndexFromPath` | function | Normalizes a file path by removing the trailing folder-index filename, returning the logical folder path |
| `findDocNodeByPath` | function | Recursively searches a `DocNode[]` tree for a node matching the given path |
| `getDocAncestorNodeIds` | function | Converts a slash-delimited node path into DOM-style IDs for each ancestor segment (used to pre-open accordion sidebar) |
| `resolveContentFetchPath` | function | Determines the actual storage path to fetch for a selected node, handling folder README resolution and no-content folders |
| `getInitialExpandedNodeIds` | function | Derives the set of accordion node IDs that should be expanded on initial load for a given path |
| `getDocSourceDefaultPath` | function | Finds the first root-level folder with a README when the tree root itself has no index file |

## Usage Example

```typescript
import {
  stripFolderIndexFromPath,
  findDocNodeByPath,
  resolveContentFetchPath,
  getInitialExpandedNodeIds,
  getDocSourceDefaultPath,
} from './doc-tree-nav'

// Normalize a path for display or URL routing
stripFolderIndexFromPath('guides/README.md') // → 'guides'
stripFolderIndexFromPath('README.md')        // → ''

// Find a node in the tree
const node = findDocNodeByPath('guides/quickstart', docStructure)

// Resolve what to actually fetch from storage
const fetchPath = resolveContentFetchPath('guides', docStructure)
// → 'guides/README.md' if the folder has hasReadme: true

// Expand ancestor accordions for a deep initial path
const openIds = getInitialExpandedNodeIds('guides/setup/install.md')
// → ['guides', 'guides-setup']

// Jump to the first meaningful default when root has no README
const defaultPath = getDocSourceDefaultPath(docStructure)
// → 'guides' (first folder with hasReadme: true)
```

## Notes

- All functions accept an optional `folderIndexFile` parameter (defaults to `DEFAULT_FOLDER_INDEX_FILE`) to support non-standard folder-index conventions.
- `DEFAULT_FOLDER_INDEX` is exported as a deprecated alias — migrate consumers to `DEFAULT_FOLDER_INDEX_FILE`.
- `resolveContentFetchPath` returns `null` for folders with no README, signaling the UI to suppress a fetch attempt.