Merge pull request #933 from Themolx/replace-with-precomp

# Conflicts:
#	crates/engine/src/tests_project_items.rs

docs/agents.md

@@ -227,6 +227,9 @@ build real projects through these interfaces; they are worked examples of everyt
 * **Several footage items at once**: `file.newCompFromSelection {single, dimensionsFrom, duration,
   sequence, overlap, overlapDuration, transition, addToRenderQueue}` is one undo step (select the
   items first: `project.select`).
+* **Where an item is used**: `project.usedIn {item?}` → `{item, count, comps: [{id, name, layers}]}`
+  counts the layers, in every comp, whose source the item is (direct uses only, as the Project
+  panel's "Name ▾, used 3 times" header; its ▾ lists the comps and opens the one picked).
 * **Locked layers** are left alone: `edit.clear`, `layer.arrange`, `layer.transform` and
   `layer.centerAnchor` skip them and fail when every target is locked ("… is locked"); Select
   All and `layer.selectNext` / `selectPrevious` step over them. Unlock with

docs/footage.md

@@ -98,6 +98,13 @@ vectors, positions and IDs are never the picture. EXtractoR reads every other la
 - **File ▸ Replace Footage ▸ File…** (Ctrl+H) points the item at another file. Pick a numbered
   file to replace it with that file's whole sequence (`file.replaceFootage {"path": …,
   "sequence": false}` for one frame).
+- **Replace with Precomposition (used N times)**, right-clicking a footage item or solid in the
+  Project panel, puts the item in a new composition of its size,
+  pixel aspect and frame rate, in the same folder, and switches every layer in every composition
+  that used the item to that composition. Layers keep their timing, transforms, effects and
+  masks, and the item stays in the project. The composition lasts as long as the footage, or as
+  the longest layer that showed a still or solid. One undo step (`file.replaceWithPrecomp
+  {"item"?}`).
 - **File ▸ Reload Footage** (Ctrl+Alt+L) reads the files again. A sequence picks up frames
   added to its folder (a render still in progress) and keeps its interpretation.