diff --git a/README.md b/README.md
index 9a565b5..93aa6f9 100644
--- a/README.md
+++ b/README.md
@@ -88,8 +88,6 @@ Builds mask and control_frames sequences for all VACE generation modes. Works st
## Mode Reference
-All diagrams show the `mask` and `control_frames` layout left-to-right (frame 0 → frame N).
-
---
### End Extend
@@ -98,10 +96,18 @@ Generate new frames **after** the source clip.
- **`split_index`** — optional trim: `0` keeps the full clip; a negative value (e.g. `-16`) drops that many frames from the end before extending.
-```
-mask: [ BLACK × source ][ WHITE × generated ]
-control_frames: [ source clip ][ GREY × generated ]
-```
+
---
@@ -111,10 +117,18 @@ Generate new frames **before** a reference portion of the source clip.
- **`split_index`** — how many frames from the start to keep as the reference tail (e.g. `24`).
-```
-mask: [ WHITE × generated ][ BLACK × reference ]
-control_frames: [ GREY × generated ][ reference frames ]
-```
+
---
@@ -124,10 +138,22 @@ Generate new frames **between** two halves of the source clip, split at `split_i
- **`split_index`** — frame index where the source is split (`0` = auto-middle). Raises an error if out of range.
-```
-mask: [ BLACK × part_a ][ WHITE × generated ][ BLACK × part_b ]
-control_frames: [ part_a ][ GREY × generated ][ part_b ]
-```
+
---
@@ -140,10 +166,22 @@ Generate a transition **between the end and start** of a clip (useful for loopin
The end segment is placed first, then the generated gap, then the start segment — so the model learns to connect the clip's end back to its beginning.
-```
-mask: [ BLACK × end_seg ][ WHITE × generated ][ BLACK × start_seg ]
-control_frames: [ end_seg ][ GREY × generated ][ start_seg ]
-```
+
---
@@ -154,16 +192,36 @@ Heal/blend **two halves** of a clip (or two separate clips) together. By default
- **`edge_frames`** — context frames taken from each side of the join point.
- **`split_index`** — unused.
-```
-Single clip: [ part_1 ][ part_2 | part_3 ][ part_4 ]
- ← edge → ← edge →
-
-Two clips: clip_1: [...| part_2 ] clip_2: [ part_3 |...]
- ← edge → ← edge →
-
-mask: [ BLACK × part_2 ][ WHITE × generated ][ BLACK × part_3 ]
-control_frames: [ part_2 ][ GREY × generated ][ part_3 ]
-```
+
---
@@ -174,10 +232,22 @@ Generate new frames **both before and after** the source clip.
- **`split_index`** — number of generated frames to place before the clip. `0` = even split (half before, half after).
- **`target_frames`** — total output frame count.
-```
-mask: [ WHITE × pre ][ BLACK × source ][ WHITE × post ]
-control_frames: [ GREY × pre ][ source clip ][ GREY × post ]
-```
+
---
@@ -187,10 +257,40 @@ Insert generated frames **between each consecutive pair** of source frames.
- **`split_index`** — number of new frames to insert per gap (min 1). `target_frames` is unused.
-```
-mask: [ B ][ W×step ][ B ][ W×step ][ B ] ...
-control_frames: [ f0][ GREY ][ f1][ GREY ][ f2] ...
-```
+
---
@@ -202,10 +302,22 @@ Regenerate a range of frames **in-place** within the source clip.
- **`edge_frames`** — number of frames to replace (clamped to remaining frames after start).
- `target_frames` is unused. Total output = `source_frames` (in-place replacement).
-```
-mask: [ BLACK × before ][ WHITE × replace ][ BLACK × after ]
-control_frames: [ before frames ][ GREY × replace ][ after frames ]
-```
+
---
@@ -223,10 +335,26 @@ Compositing formula per pixel:
control_frames = source × (1 − mask) + grey × mask
```
-```
-mask: [ per-pixel mask broadcast to (B, H, W, 3) ]
-control_frames: [ source pixels where mask=0, grey where mask=1 ]
-```
+
---
@@ -239,12 +367,39 @@ Place keyframe images at specific positions within a `target_frames`-length outp
- **`keyframe_positions`** *(optional)* — comma-separated frame indices (e.g. `"0,20,50,80"`). Must have one value per source frame, sorted ascending, no duplicates, all within [0, target_frames-1]. Leave empty for **auto-spread** (first keyframe at frame 0, last at `target_frames-1`, others evenly distributed).
- **`split_index`**, **`edge_frames`** — unused.
-```
-Example: 4 keyframes, target_frames=81, positions auto-spread to 0,27,53,80
-
-mask: [ B ][ W×26 ][ B ][ W×25 ][ B ][ W×26 ][ B ]
-control_frames: [ k0][ GREY ][ k1][ GREY ][ k2][ GREY ][ k3]
-```
+
---
@@ -296,16 +451,48 @@ Merge: result = original[0:121] + vace[0:81] + original[153:274]
### Wiring Diagram
-```
-[Load Video]
- │
- ├─ source_clip ──→ [VACESourcePrep] ─┬─ trimmed_clip ──→ [MaskGen] ─→ [Sampler]
- │ ├─ mode ───────────→ [MaskGen] │
- │ └─ vace_pipe ──────────────────┐ │
- │ │ │
- └─ source_clip ───────────────────────────────────────→ [VACEMergeBack] ←┘
- vace_output
-```
+
---