SimonCropp · Oct 4, 2026 · Oct 4, 2026
diff --git a/claude.md b/claude.md
@@ -737,6 +737,47 @@ the comment there about not caching "nothing staged" asks for.
   `Application.Run()`.
 - Allows accepting/discarding diffs from system tray
 
+**Source and derived files (`DiffRunner.LaunchDerived`, `QueueProjection.Derivation`):**
+- A snapshot library that splits a document into files (Verify's converters: a png and the text
+  of each page, a csv per sheet) says so. A derived pending file names its **source** by the
+  source's received path: one level, only while the source is itself pending, and the caller
+  launches the source first. Not "group", which here already means solution.
+- The marker is additive on all three wires and is only ever relayed. `source:` on a `move`,
+  `diff` or `delete` request (`ViewerMessage.Source`); a `derived: key|source key` line of its
+  own on a listing (`ViewerResponseMove.SourceKey`), as `held:` is and for its reason; and a
+  trailing `"Source"` on the piper's Move and Delete payloads, which are byte for byte what they
+  were without it. A new payload `Type` would be dropped whole by an older tray, where a property
+  it does not know is skipped and the file still tracked. `IQueueOwner.TrackMove` and
+  `TrackDelete` take the source as a required argument, so no owner can leave it out.
+- The policy is the library's and has one condition, `PendingFiles.Draws`: the tool resolved for
+  the source is the viewer, the source is a document, and that copy reads documents
+  (`ViewerDocuments.ReadBy`). Then `InnerLaunch` tracks the derived pair and answers
+  `AlreadyRunningAndSupportsRefresh` before a tool is resolved for it: no window, nothing against
+  `MaxInstance`, and no empty target written for a tool that would have required one. In every
+  other case the launch is the one it always was, with the source said to whatever tracks the
+  pair. That is what keeps the other diff tools working, and why the tray decides none of it.
+  `PendingFiles.AddDerived` gives a tray the viewer's exe and `RelaunchFor` arguments, so the
+  file counts as open and "Accept all open" takes it. Nobody to take it falls through to the
+  ordinary launch.
+- The tray stores and relays (`TrackedMove.Source`, `TrackedDelete.Source`), and its menu is
+  unchanged. A source changing makes a new tracked object, since `ITrackedFiles.Version` is their
+  identity. `Tracker.UntrackDerivedFrom` drops the derived moves of a settled document whose
+  received files have gone, which would otherwise be ordinary rows until the next scan.
+- The fold is the viewer's and is a view (`QueueProjection.Derivation`): D sits beneath S when
+  `D.SourceKey == S.Key`, S is a move naming no source of its own, `S.IsDocument`, and the two
+  share a solution. Anything else is an ordinary row, which is the degrade for an older owner, a
+  document accepted on its own, and a viewer with no documents folder. `Order` puts attached
+  entries straight after their source, `Walk` gives them a slot only while the source's key is in
+  `SessionState.Unfolded`, and the selection never rests on an entry with no row (`Seen`). Labels
+  only, so no head and no ABI changed: the menu's Expand and Collapse, and a click on the row of
+  the document already selected (`ViewerProgram.ClickEntry`).
+- A window's accept or discard of a document with files beneath it is a batch over them all
+  (`ViewerSession.BeginAcceptWithDerived`, `AcceptBatch.Cascade`), the document last
+  (`FilesInBatchOrder`): taken first it left its files behind as ordinary rows, one frame each.
+  The batch's rules stand, so a file that fails is kept and counted. An accept by key over the
+  wire is still one entry, as asked; an attached viewer sends the derived files as a group accept
+  and then the document (`ViewerProgram.DispatchWithDerived`).
+
 **Packaging.Tests (`src/Packaging.Tests/`):**
 - Opens each `.nupkg` a Release build drops in `nugets` and snapshots its entry list, plus a few
   invariants a snapshot states poorly: an apphost with no assembly beside it, a viewer file in the

diff --git a/docs/diff-tool.md b/docs/diff-tool.md
@@ -54,6 +54,8 @@ This value can be changed using an environment variable or by explicitly specify
 
 The count includes [DiffEngineViewer](/docs/viewer.md), but only when a viewer has to be started. Handing a pair to one already on screen opens no window and so spends nothing.
 
+Neither does a file [derived from a document](/docs/viewer.md#files-derived-from-a-document) the viewer is drawing: it is shown beneath the document rather than in a tool of its own. A document split into a file per page would otherwise spend the whole allowance on one test.
+
 
 ### Using an environment variable
 
@@ -319,9 +321,9 @@ DiffTools.UseOrder(DiffTool.DiffEngineViewer);
   * Scanned paths:
     * `%USERPROFILE%\.dotnet\tools\DiffEngineViewer.exe`
     * `%USERPROFILE%\.dotnet\tools\.store\diffenginetray\*\diffenginetray\*\tools\*\any\viewer\win-x64\DiffEngineViewer.exe`
-    * `%NUGET_PACKAGES%\diffengine\20.6.0\tools\viewer\win-x64\DiffEngineViewer.exe`
+    * `%NUGET_PACKAGES%\diffengine\20.7.0-beta.1\tools\viewer\win-x64\DiffEngineViewer.exe`
     * `%NUGET_PACKAGES%\diffengine\*\tools\viewer\win-x64\DiffEngineViewer.exe`
-    * `%USERPROFILE%\.nuget\packages\diffengine\20.6.0\tools\viewer\win-x64\DiffEngineViewer.exe`
+    * `%USERPROFILE%\.nuget\packages\diffengine\20.7.0-beta.1\tools\viewer\win-x64\DiffEngineViewer.exe`
     * `%USERPROFILE%\.nuget\packages\diffengine\*\tools\viewer\win-x64\DiffEngineViewer.exe`
     * `%PATH%DiffEngineViewer.exe`
 
@@ -337,9 +339,9 @@ DiffTools.UseOrder(DiffTool.DiffEngineViewer);
    ```
   * Scanned paths:
     * `%HOME%/.dotnet/tools/DiffEngineViewer`
-    * `%NUGET_PACKAGES%/diffengine/20.6.0/tools/viewer/osx-x64/DiffEngineViewer`
+    * `%NUGET_PACKAGES%/diffengine/20.7.0-beta.1/tools/viewer/osx-x64/DiffEngineViewer`
     * `%NUGET_PACKAGES%/diffengine/*/tools/viewer/osx-x64/DiffEngineViewer`
-    * `%HOME%/.nuget/packages/diffengine/20.6.0/tools/viewer/osx-x64/DiffEngineViewer`
+    * `%HOME%/.nuget/packages/diffengine/20.7.0-beta.1/tools/viewer/osx-x64/DiffEngineViewer`
     * `%HOME%/.nuget/packages/diffengine/*/tools/viewer/osx-x64/DiffEngineViewer`
     * `%PATH%DiffEngineViewer`
 
@@ -355,9 +357,9 @@ DiffTools.UseOrder(DiffTool.DiffEngineViewer);
    ```
   * Scanned paths:
     * `%HOME%/.dotnet/tools/DiffEngineViewer`
-    * `%NUGET_PACKAGES%/diffengine/20.6.0/tools/viewer/linux-x64/DiffEngineViewer`
+    * `%NUGET_PACKAGES%/diffengine/20.7.0-beta.1/tools/viewer/linux-x64/DiffEngineViewer`
     * `%NUGET_PACKAGES%/diffengine/*/tools/viewer/linux-x64/DiffEngineViewer`
-    * `%HOME%/.nuget/packages/diffengine/20.6.0/tools/viewer/linux-x64/DiffEngineViewer`
+    * `%HOME%/.nuget/packages/diffengine/20.7.0-beta.1/tools/viewer/linux-x64/DiffEngineViewer`
     * `%HOME%/.nuget/packages/diffengine/*/tools/viewer/linux-x64/DiffEngineViewer`
     * `%PATH%DiffEngineViewer`
 

diff --git a/docs/mdsource/diff-tool.source.md b/docs/mdsource/diff-tool.source.md
@@ -47,6 +47,8 @@ This value can be changed using an environment variable or by explicitly specify
 
 The count includes [DiffEngineViewer](/docs/viewer.md), but only when a viewer has to be started. Handing a pair to one already on screen opens no window and so spends nothing.
 
+Neither does a file [derived from a document](/docs/viewer.md#files-derived-from-a-document) the viewer is drawing: it is shown beneath the document rather than in a tool of its own. A document split into a file per page would otherwise spend the whole allowance on one test.
+
 
 ### Using an environment variable
 

diff --git a/docs/mdsource/tray.source.md b/docs/mdsource/tray.source.md
@@ -190,6 +190,17 @@ snippet: PiperTest.MoveJson.verified.txt
 snippet: PiperTest.DeleteJson.verified.txt
 
 
+### Derived from another file
+
+A move or a delete of a file that was [derived from a document](/docs/viewer.md#files-derived-from-a-document) names the temp file of the pending move it was derived from, in a `Source` property that is absent otherwise:
+
+snippet: PiperTest.MoveWithSourceJson.verified.txt
+
+snippet: PiperTest.DeleteWithSourceJson.verified.txt
+
+The tray tracks such a file as it tracks any other, so it is listed in the menu and taken by an accept-all. The property is only passed on to the viewer, which is what folds the file beneath its document. A tray older than the property ignores it.
+
+
 ## Logging Directory
 
 Beside the installed tool, so it moves with the target framework the tray is built for:

diff --git a/docs/mdsource/viewer.source.md b/docs/mdsource/viewer.source.md
@@ -202,6 +202,7 @@ Every row of the pending column answers a right-click:
 
  * An inline snapshot offers **Accept**, **Discard** and **Open source file**, plus **Show next variant** when frameworks disagree about it.
  * A move offers **Accept move**, **Discard** and **Open target directory**; a delete offers **Accept delete**, **Discard** and **Open directory**.
+ * A document with [files derived from it](#files-derived-from-a-document) counts them in the first two, **Accept move +5** and **Discard +5**, and adds **Expand** or **Collapse**.
  * A solution header offers **Accept all in ...** and **Discard all in ...** for that solution only, and a test sub-header the same for that test's changes. Bulk accepts skip conflicted snapshots, the way accept-all does.
  * Every entry also offers **Copy selection** when there is one, and a **Copy** item per pane, named after that pane, which copies the whole side. A side with nothing in it — the expected side of a brand new snapshot, or what is left after a delete — gets no item rather than one that copies nothing.
 
@@ -236,7 +237,7 @@ When [DiffEngineTray](/docs/tray.md) owns the queue, the viewer also lists the t
 
 **Accept all** on a tray-owned queue sweeps everything the window shows: deletes, moves and snapshots, with conflicted snapshots skipped and anything locked kept pending and counted. The deletes are the ones pending when it began, and are held back when a snapshot was not written. One for a file that a move in the same sweep has written is left pending.
 
-A viewer that owns the queue itself never shows moves or deletes, because DiffEngine only sends them to a running tray.
+A viewer that owns the queue itself is sent them directly when [no tray is running](#with-no-tray), and shows them the same way.
 
 
 ## Images
@@ -307,6 +308,36 @@ An SVG is drawn with scripts, external images and external elements turned off.
 DiffEngine offers the viewer for `.pdf`, `.docx`, `.xlsx`, `.pptx` and the map extensions only when the copy it resolved carries the folder. The viewer is last in the default tool order, so Word, Excel, Beyond Compare or DeltaWalker are still preferred where installed.
 
 
+### Files derived from a document
+
+A snapshot library often verifies more than the document itself: a png of each page, the text read out of it, a csv per sheet. Each is a received file of its own, and each would be a row of its own, asking for one change to be accepted again once per file, when the document's row has already shown its pages and its text.
+
+So a caller can say that a file was derived from a document, with `DiffRunner.LaunchDerived` in place of `DiffRunner.Launch`. [Verify](https://github.com/VerifyTests/Verify) does, for what its converters split out of a document. While the viewer is drawing that document, a derived file opens no tool of its own, spends nothing against [MaxInstancesToLaunch](/docs/diff-tool.md#maxinstancestolaunch), and has no row. It is counted on the document's:
+
+```
++ Sample.Test (pdf) (5)
+```
+
+Accepting the document accepts the files beneath it as well, the document last, and the button and the menu say how many: **Accept move +5**. **Discard +5** discards them the same way. A file that could not be written stays pending and the closing message counts it, as an accept-all does. A page the document no longer has is a pending delete beneath it, carried out when the document is accepted. **Accept all** counts and takes every file, folded or not.
+
+The row's marker is the one a header has. **Expand** in the row's right-click menu, or a click on the row once it is the one selected, gives each derived file a row under the document, named by what it adds to the document's name:
+
+```
+- Sample.Test (pdf) (5)
+  (txt)
+  #page_0001 (png)
+  #page_0001 (txt)
+  #page_0002 (png)
+  #page_0003.verified.png
+```
+
+Selected, a derived file is the ordinary pair it also is, and its **Accept move** takes that file alone. `Tab` steps over the files of a folded document, a folded document's row carries the `!` of a failure beneath it, and anything that selects a derived file from outside the window unfolds its document.
+
+Folding needs the document on screen as a document. A derived file is an ordinary row when its document is not pending, when the copy of the viewer running has no `documents` folder, or when the document was accepted on its own from the tray's menu. When the document went to another tool, such as Word or Beyond Compare, each derived file is opened in its own tool as it always has been. The viewer is last in the default [tool order](/docs/diff-tool.order.md), so on a machine with one of those installed it has to be ordered first for a document to reach it.
+
+What is accepted unseen is accepted on the strength of the viewer's own drawing of the document, which is not necessarily the renderer that produced the page files. Expanding the row shows them.
+
+
 ### Maps
 
 Maps are read and drawn with [GeoConvert](https://github.com/Papyrine/GeoConvert). Each is one picture, as an SVG is, so there are no pages to turn, and the status line says whether the two draw the same.

diff --git a/docs/tray.md b/docs/tray.md
@@ -212,18 +212,49 @@ The case it exists for is a test suite that needs the launch to happen but does
 <a id='snippet-PiperTest.DeleteJson.verified.txt'></a>
 ```txt
 {
+"Type":"Delete",
+"File":"theFilePath"
+}
+```
+<sup><a href='/src/DiffEngineTray.Tests/PiperTest.DeleteJson.verified.txt#L1-L4' title='Snippet source file'>snippet source</a> | <a href='#snippet-PiperTest.DeleteJson.verified.txt' title='Start of snippet'>anchor</a></sup>
+<!-- endSnippet -->
+
+
+### Derived from another file
+
+A move or a delete of a file that was [derived from a document](/docs/viewer.md#files-derived-from-a-document) names the temp file of the pending move it was derived from, in a `Source` property that is absent otherwise:
+
+<!-- snippet: PiperTest.MoveWithSourceJson.verified.txt -->
+<a id='snippet-PiperTest.MoveWithSourceJson.verified.txt'></a>
+```txt
+{
 "Type":"Move",
 "Temp":"theTempFilePath",
 "Target":"theTargetFilePath",
 "CanKill":true,
 "Exe":"theExePath",
 "Arguments":"TheArguments",
-"ProcessId":1000
+"ProcessId":1000,
+"Source":"theSourceTempFilePath"
+}
+```
+<sup><a href='/src/DiffEngineTray.Tests/PiperTest.MoveWithSourceJson.verified.txt#L1-L10' title='Snippet source file'>snippet source</a> | <a href='#snippet-PiperTest.MoveWithSourceJson.verified.txt' title='Start of snippet'>anchor</a></sup>
+<!-- endSnippet -->
+
+<!-- snippet: PiperTest.DeleteWithSourceJson.verified.txt -->
+<a id='snippet-PiperTest.DeleteWithSourceJson.verified.txt'></a>
+```txt
+{
+"Type":"Delete",
+"File":"theFilePath",
+"Source":"theSourceTempFilePath"
 }
 ```
-<sup><a href='/src/DiffEngineTray.Tests/PiperTest.DeleteJson.verified.txt#L1-L9' title='Snippet source file'>snippet source</a> | <a href='#snippet-PiperTest.DeleteJson.verified.txt' title='Start of snippet'>anchor</a></sup>
+<sup><a href='/src/DiffEngineTray.Tests/PiperTest.DeleteWithSourceJson.verified.txt#L1-L5' title='Snippet source file'>snippet source</a> | <a href='#snippet-PiperTest.DeleteWithSourceJson.verified.txt' title='Start of snippet'>anchor</a></sup>
 <!-- endSnippet -->
 
+The tray tracks such a file as it tracks any other, so it is listed in the menu and taken by an accept-all. The property is only passed on to the viewer, which is what folds the file beneath its document. A tray older than the property ignores it.
+
 
 ## Logging Directory
Original file line number	Diff line number	Diff line change
Expand Up		@@ -47,6 +47,8 @@ This value can be changed using an environment variable or by explicitly specify

		The count includes [DiffEngineViewer](/docs/viewer.md), but only when a viewer has to be started. Handing a pair to one already on screen opens no window and so spends nothing.

		Neither does a file [derived from a document](/docs/viewer.md#files-derived-from-a-document) the viewer is drawing: it is shown beneath the document rather than in a tool of its own. A document split into a file per page would otherwise spend the whole allowance on one test.


		### Using an environment variable

Expand Down