@ryhrm-gz/xincodo-lib/skills/editing-preview-workflow/references/traversal-paths.md

Utilities for working with Xincodo body documents.

# Traversal Paths

`TraversalPath` identifies a location inside `Body` data.

```ts
type TraversalPathSegment = {
  key:
    | "content"
    | "children"
    | "items"
    | "rows"
    | "cells"
    | "images"
    | "richText"
    | "caption"
    | "title";
  index?: number;
};

type TraversalPath = readonly TraversalPathSegment[];
```

## Block Paths

Root block at `content[0]`:

```ts
[{ key: "content", index: 0 }];
```

Child block of a text/callout/quote block:

```ts
[
  { key: "content", index: 0 },
  { key: "children", index: 0 },
];
```

Block inside a list item:

```ts
[
  { key: "content", index: 0 },
  { key: "items", index: 0 },
  { key: "children", index: 0 },
];
```

## Path Safety

- Prefer stable ids for editor state.
- Resolve a fresh path with `findBlockPathById` immediately before editing.
- Do not reuse old paths after insert, remove, replace, or move operations.
- Block edit helpers need block paths.
- `updateRichTextAtPath` needs rich text field paths, not block paths.

## Visitor Context

`walkBody` supplies paths for blocks, rich text, inlines, list items, table
cells, and gallery images. Use visitor-provided paths when editing rich text
fields or collecting metadata.