Per os renderers (#733)

* Snapshot the contents of every package

Package content is assembled by MSBuild from several unrelated mechanisms and
nothing in the build asserted the result, so a stray or missing file only
surfaced once it was on nuget.org.

The baselines record today's output, which includes a defect worth naming: the
tray package carries DiffEngineViewer.exe, its runtimeconfig and all six native
renderers, but no DiffEngineViewer.dll. That apphost cannot start, and the
natives are 13 MB of dead weight in a Windows only package. Fixed next, so the
removal reads as a diff.

Windows only via the solution file. Release-NotWindows drops DiffEngineTray, so
a run there would be describing an incomplete release.

* Stop the viewer leaking into the tray package

A solution level BuildDependency is treated as a reference, not just as
ordering. DiffEngine declared one on DiffEngineViewer to make sure the viewer
was built before PublishViewerHeads shelled out to dotnet publish, and the
viewer is an Exe carrying six native renderers as content, so all of it was
copied into DiffEngine's output for each of its eight target frameworks and
then on into DiffEngineTray through the ordinary project reference.

DiffEngine's own package was unaffected, because lib/{tfm} only takes the
primary assembly. DiffEngineTray's was not: PackAsTool packages the whole
publish directory, so it shipped an apphost with no assembly beside it and
13 MB of renderers for platforms it does not run on. 6,421,352 bytes to
363,032.

It takes a solution build to reproduce, which is what publish-nuget.yml runs,
so any DiffEngineTray package published since the viewer landed carries it.
The apphost was never startable, since the assembly it needs was not copied
either, so the effect was dead weight rather than a broken command.

Ordering is now a project reference in DiffEngine.csproj, where
ReferenceOutputAssembly, Private and ExcludeAssets can say that nothing is
wanted from it, and where it can be limited to the one target framework the
viewer has.

The three invariants added here are the ones a content snapshot states poorly:
an apphost with no assembly, a viewer file in the tray, and an incomplete
bundled head.

* Put an interface where the renderer is

ViewerWindow was already the only type touching the native shim and already had
close to the right shape, so this mostly promotes it: TryOpen becomes an
OpenWindow delegate returning null with a message, Poll, SetHidden and Focus
become instance members, and the class becomes NativeViewerWindow.

Program splits in two. ViewerProgram.Run takes the renderer to use, so the
queue semantics, the wire protocol and the loop are shared. Program.Main keeps
only the choice of renderer and the NativeResolver registration that goes with
it, which is the shape each platform head will take.

Loop itself is untouched, which is the point: the scroll amplification, the
button index lookup and the tray-running close-means-hide rule stay in one
place rather than being reimplemented per platform.

ViewerInput moves out of Native, having never had anything native about it.

* Split the viewer into a core and one head per OS

A portable RID agnostic tool package and a per platform GUI framework cannot
coexist: WinForms needs Microsoft.WindowsDesktop.App named in
runtimeconfig.json, which fails to start on macOS and Linux. The single package
only ever worked because the platform variation was native files that
NativeResolver picks at load time.

So DiffEngineViewer becomes a library, and DiffEngineViewer.Windows, .Mac and
.Linux are the packages. All three still build a DiffEngineViewer apphost, so
tools/viewer keeps its shape and BundledViewerDirectory, ViewerLauncher and the
tool definition are all untouched. The core takes the .Core assembly name to
leave the plain one for the heads, which is the name the launcher looks up.

The committed renderers move to the head that loads them, which is also the
statement that the Windows head is about to stop having any.

Every head is still the native renderer here. Swapping the Windows one for
WinForms is the next commit, so that diff is only the renderer.

A user now downloads 1.0, 2.3 or 3.5 MB rather than 6.2, and DiffEngine.nupkg
is unchanged apart from carrying DiffEngineViewer.Core.dll per RID.

* Render with WinForms on Windows

The Screen model was already renderer agnostic, so this head consumes it
directly: no marshalling layer, no flat blittable frame description, and no
committed binary. The two Windows renderers, 1.9 MB, are deleted.

One owner drawn surface rather than a control per pane, because ScreenBuilder
has already sliced each pane to the rows that fit. A scrolling control would
want to own that decision, and the text snapshots would stop describing what
this draws. The footer buttons are real controls, so they keep native focus,
keyboard access and theming.

Pumped through DoEvents rather than inverted onto Application.Run. ViewerProgram
owns the loop for all three heads, and keeping it there is what keeps the scroll
amplification, the button lookup and the close-means-hide rule in one place. The
usual objections to DoEvents do not apply: no modal dialogs, no nested message
loops, and session state already behind its own lock.

Two things this fixes rather than ports. The window reports the character grid
it measured from the font instead of dividing pixels by a hardcoded 9 by 18,
which is what makes it right on a scaled display. And closing is FormClosing
with Cancel, rather than declaring a GLFW symbol by hand because raylib latches
its close flag and offers no way to clear it.

Text goes through GDI+ with grayscale antialiasing rather than GDI, which
honours whatever ClearType setting the machine has. That is what lets the four
baselines here be committed at all.

DiffEngineViewer.Windows is 275 KB against the 6.2 MB the one portable package
used to be, and DiffEngine.nupkg drops from 9.38 MB to 8.63 MB.

* Report the character grid in cells, not pixels

DeviewInput.columns and rows carried pixels, and NativeViewerWindow divided
them by a hardcoded 9 by 18 measured once for JetBrains Mono at 15px. That is
the whole of the viewer's DPI handling, and it is wrong on any scaled display:
the grid ScreenBuilder slices to is either larger than the window or leaves it
half empty.

The shim is the only side that knows what font it loaded, so it measures and
reports cells. The managed side keeps only the floors, which are the app's rule
rather than the renderer's. DEVIEW_VERSION goes to 2, since the struct is the
same shape but a field means something else, which is exactly the case a
version check has to catch.

The WinForms head already did this properly by measuring GDI+ metrics, so this
brings the other two into line rather than introducing the idea.

The committed Linux and macOS binaries are still version 1, so the native
smoke job in test.yml fails until build-native regenerates them. The unix job
does not: it builds the Linux shim from source, which is also why the four
pixel baselines are unaffected.

* Point CI and the docs at the per OS heads

build-native drops its two Windows matrix entries, and lays its artifacts out
as src/{head}/runtimes/{rid}/native so the propose job can merge them straight
into the head that loads them. The native smoke job loses win-arm64 for the
same reason. publish-nuget checks four RIDs rather than six; its push step
already enumerates whatever is in nugets, so the three viewer packages need
nothing.

Docs now say the renderer is per platform and name the three packages, with
the reason a portable one is not possible.

* Render with AppKit and Core Text on macOS

Implements the same eight exports as native/, so the managed side is untouched:
Deview, DeviewStructs, ScreenPayload, NativeResolver and NativeViewerWindow all
stay exactly as they are and neither knows which library it loaded.

The header is imported rather than redeclared, because Swift does not guarantee
struct layout and two copies of an ABI is the bug DEVIEW_VERSION exists to
catch. deview.h grows a DEVIEW_TYPES_ONLY guard so this side can take the
structs without also taking prototypes for symbols it is about to define.

C# keeps the loop. deview_present drains NSApp.nextEvent up to a deadline and
returns, rather than handing control to NSApplication.run, which is what keeps
the scroll amplification, the button lookup and the close-means-hide rule in
ViewerProgram for every platform. The deadline doubles as the frame throttle.

No app bundle: setActivationPolicy plus finishLaunching is enough for a window
that takes focus, the same thing GLFW does for the Linux build. Nothing is
flipped either; layout is written top down and converted once, rather than
fighting the text matrix to keep glyphs upright.

deview_capture draws into a bitmap context of its own making rather than asking
the view for one. bitmapImageRepForCachingDisplay would inherit the window's
backing scale, so a committed baseline would only match on the kind of display
that produced it. Scale, colour space and the six font smoothing and subpixel
switches are pinned there instead, which also means capture needs no window
server.

Linux and macOS now render differently, so PixelTests gains UniqueForOSPlatform
and the existing baselines become .Linux. The macOS set does not exist yet: it
has to be produced by the pinned macos-14 runner and accepted from the received
artifacts, the same way the Linux one was.

Not compiled. There is no macOS here to build or run it on, so the first real
feedback is CI.

* Collect a universal dylib rather than the first one found

swift build --arch arm64 --arch x86_64 compiles both slices but leaves a per
architecture dylib in more than one place, so taking the first match gave an
arm64 only binary. It shipped to both osx RIDs, and the lipo check in the
native smoke job caught it, which is what that check is for.

Every candidate is now checked, and if none is already universal they are
merged, so the only thing collectable is a fat binary. The arch assertion moves
into this step too: finding out at collect time beats finding out a job later.

* Leave the SBOM out of the package snapshots

DiffEngine references Microsoft.Sbom.Targets under a condition on the CI
variable, so a release package carries two _manifest entries that a local pack
does not. The baselines were taken locally, so the Windows job failed on the
difference rather than on anything being wrong.

Dropped from the entry lists so one baseline describes both. Absence would then
go unnoticed, so the half that can still be checked is: on CI, the SBOM is
there.

* Skip the dSYM when looking for the dylib

The debug bundle holds a DWARF file of the same name, and it is universal too,
so the arch check would have accepted it and shipped symbols as the library.
Ordering happened to favour the real product this time.

* Rebuild native renderer binaries

* Do not create a window when macOS starts hidden

The pixel snapshots crashed with "NSWindow should only be instantiated on the
main thread". TUnit runs Before(Class) on a worker, and deview_init built a
window there. The app was never at risk: ViewerProgram.Run is called from Main,
which is the main thread.

A hidden start now builds only the renderer, which is all capture needs, since
it draws into a bitmap context of its own making. The window is deferred to
deview_set_hidden, so the ABI contract is unchanged rather than diverging from
the Linux head, and the header says so.

Test passed on macOS through all of this because NativeTests only calls
deview_version, which touches no AppKit.

* Rebuild native renderer binaries

* Accept the macOS pixel baselines

Produced by the pinned macos-14 runner, which is the only place they can come
from: Core Text is the system text stack, so a developer machine renders
correctly but not identically.

Checked against the WinForms and Linux renders of the same four screens rather
than accepted on the strength of the tests going green. Between them they cover
the three column inline layout and the two column file one, added and modified
rows, filler, the queue selection, a disabled button and a status message.

* Declare the usings that a rebuild loses

ProjectDefaults supplies System.Collections, System.Diagnostics,
System.Reflection and System.Collections.Concurrent through a preprocessed
content file, which NuGet materialises into obj and records in FileWrites. A
rebuild deletes it and nothing puts it back in the same invocation, so the
compile runs without those four namespaces and every use of Process,
DebuggerDisplay, ConcurrentDictionary or the non generic IDictionary fails.

Reproducible on main with dotnet build src --no-incremental, and the reason
nobody noticed is that CI always builds a fresh clone and an incremental build
never removes the file. Rider rebuilding is what found it.

Declaring them here puts them in the generated GlobalUsings instead, which the
SDK owns and a clean does not touch. Overlapping with the content file is
harmless: a duplicate global using is not even a warning, and warnings are
errors here.

---------

Co-authored-by: SimonCropp <122666+SimonCropp@users.noreply.github.com>

Author: SimonCropp

.github/workflows/build-native.yml

@@ -1,7 +1,8 @@
 name: Build native
 
 # Produces the diffengine_viewer binaries committed under
-# src/DiffEngineViewer/runtimes/{rid}/native.
+# src/DiffEngineViewer.{Linux,Mac}/runtimes/{rid}/native, in the head that loads them. There is no
+# Windows equivalent: that head renders with WinForms.
 #
 # They are committed rather than built during a normal build so that a plain
 # `dotnet build src --configuration Release` produces a shippable package on any machine, and
@@ -34,12 +35,7 @@ jobs:
       fail-fast: false
       matrix:
         include:
-          - rid: win-x64
-            os: windows-latest
-            generator: -A x64
-          - rid: win-arm64
-            os: windows-latest
-            generator: -A ARM64
+          # No Windows entries. That head renders with WinForms and loads no native library.
           - rid: linux-x64
             os: ubuntu-24.04
           - rid: linux-arm64
@@ -61,40 +57,83 @@ jobs:
             libgl1-mesa-dev libglu1-mesa-dev libwayland-dev libxkbcommon-dev
 
       - name: Configure
-        shell: bash
-        run: |
-          if [ "${{ matrix.rid }}" = "osx" ]; then
-            cmake -S native -B build -DCMAKE_BUILD_TYPE=Release \
-              -DCMAKE_OSX_ARCHITECTURES="arm64;x86_64"
-          elif [ "${{ runner.os }}" = "Windows" ]; then
-            cmake -S native -B build ${{ matrix.generator }}
-          else
-            cmake -S native -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
-          fi
+        if: matrix.rid != 'osx'
+        run: cmake -S native -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
 
       - name: Build
+        if: matrix.rid != 'osx'
         run: cmake --build build --config Release
 
+      # macOS draws with AppKit and Core Text rather than raylib and ImGui, so it is a Swift
+      # package rather than a CMake project. Both --arch flags in one invocation produce a
+      # universal binary, so there is no separate lipo step.
+      #
+      # Nothing of the Swift runtime is shipped: it has been part of macOS since 10.14.4, which is
+      # why this dylib is a fraction of the size of the one it replaced.
+      - name: Build
+        if: matrix.rid == 'osx'
+        run: swift build -c release --arch arm64 --arch x86_64 --package-path native/swift
+
       - name: Collect
         shell: bash
         run: |
+          # Laid out as src/{head}/runtimes/{rid}/native, so the propose job below can merge every
+          # artifact straight into src and the binaries land in the head that loads them.
           collect() {
-            mkdir -p "artifacts/$1/native"
-            cp "$2" "artifacts/$1/native/"
+            mkdir -p "artifacts/$1/runtimes/$2/native"
+            cp "$3" "artifacts/$1/runtimes/$2/native/"
           }
           case "${{ matrix.rid }}" in
-            win-*)
-              collect "${{ matrix.rid }}" build/Release/diffengine_viewer.dll
-              ;;
             linux-*)
               strip build/libdiffengine_viewer.so
-              collect "${{ matrix.rid }}" build/libdiffengine_viewer.so
+              collect DiffEngineViewer.Linux "${{ matrix.rid }}" build/libdiffengine_viewer.so
               ;;
             osx)
-              strip -x build/libdiffengine_viewer.dylib
+              # swift build leaves a per architecture dylib in more than one place, so taking the
+              # first one found gives a single slice binary that loads on half the Macs in the
+              # world. Every candidate is checked, and if none is already universal they are
+              # merged, so the only thing that can be collected is a fat binary.
+              # The dSYM contains a DWARF file of the same name which is also universal, so the
+              # arch check below would happily accept it and ship debug symbols as the library.
+              candidates=$(find native/swift/.build -name libdiffengine_viewer.dylib -not -path '*.dSYM/*')
+              if [ -z "$candidates" ]; then
+                echo "::error::swift build produced no libdiffengine_viewer.dylib"
+                exit 1
+              fi
+
+              echo "$candidates" | while read -r candidate; do
+                echo "$candidate: $(lipo -archs "$candidate" 2>/dev/null)"
+              done
+
+              dylib=""
+              for candidate in $candidates; do
+                archs=$(lipo -archs "$candidate" 2>/dev/null || echo "")
+                if [[ "$archs" == *x86_64* && "$archs" == *arm64* ]]; then
+                  dylib="$candidate"
+                  break
+                fi
+              done
+
+              if [ -z "$dylib" ]; then
+                dylib=universal/libdiffengine_viewer.dylib
+                mkdir -p universal
+                # shellcheck disable=SC2086
+                lipo -create $candidates -output "$dylib"
+              fi
+
+              archs=$(lipo -archs "$dylib")
+              echo "collecting $dylib: $archs"
+              for arch in x86_64 arm64; do
+                case " $archs " in
+                  *" $arch "*) ;;
+                  *) echo "::error::$dylib is missing the $arch slice"; exit 1 ;;
+                esac
+              done
+
+              strip -x "$dylib"
               # The dylib is universal, so both macOS RIDs get the same file.
-              collect osx-x64 build/libdiffengine_viewer.dylib
-              collect osx-arm64 build/libdiffengine_viewer.dylib
+              collect DiffEngineViewer.Mac osx-x64 "$dylib"
+              collect DiffEngineViewer.Mac osx-arm64 "$dylib"
               ;;
           esac
           ls -lhR artifacts
@@ -133,11 +172,11 @@ jobs:
         with:
           pattern: native-*
           merge-multiple: true
-          path: src/DiffEngineViewer/runtimes
+          path: src
 
       - name: Show what changed
         run: |
-          ls -lhR src/DiffEngineViewer/runtimes
+          ls -lhR src/DiffEngineViewer.Linux/runtimes src/DiffEngineViewer.Mac/runtimes
           git status --short
 
       # A PR rather than a direct push: these are binaries, so the diff is not reviewable and the
@@ -151,7 +190,10 @@ jobs:
           title: 'Rebuild native renderer binaries'
           commit-message: 'Rebuild native renderer binaries'
           body: |
-            Rebuilt `diffengine_viewer` from `native/` for all six RIDs.
+            Rebuilt `diffengine_viewer` from `native/` for the four RIDs that load one.
+            Windows is not among them: that head renders with WinForms.
 
             Produced by the `build-native` workflow from ${{ github.sha }}.
-          add-paths: src/DiffEngineViewer/runtimes
+          add-paths: |
+            src/DiffEngineViewer.Linux/runtimes
+            src/DiffEngineViewer.Mac/runtimes

.github/workflows/publish-nuget.yml

@@ -59,13 +59,18 @@ jobs:
         shell: bash
         run: |
           missing=0
-          for rid in win-x64 win-arm64 linux-x64 linux-arm64 osx-x64 osx-arm64; do
-            directory="src/DiffEngineViewer/runtimes/$rid/native"
+          check() {
+            directory="src/$1/runtimes/$2/native"
             if [ -z "$(ls -A "$directory" 2>/dev/null)" ]; then
-              echo "::error::No native renderer for $rid. Run the build-native workflow."
+              echo "::error::No native renderer for $2. Run the build-native workflow."
               missing=1
             fi
-          done
+          }
+          # No Windows RIDs: that head renders with WinForms and loads no native library.
+          check DiffEngineViewer.Linux linux-x64
+          check DiffEngineViewer.Linux linux-arm64
+          check DiffEngineViewer.Mac osx-x64
+          check DiffEngineViewer.Mac osx-arm64
           exit $missing
 
       # Enumerated rather than passed as a glob. This job runs on Windows, where the shell is pwsh

.github/workflows/test.yml

@@ -66,7 +66,9 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        os: [ubuntu-latest, macos-latest]
+        # macOS is pinned rather than latest, because it carries committed pixel baselines and
+        # Core Text rasterisation moves between OS versions. Same image build-native uses.
+        os: [ubuntu-latest, macos-14]
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -104,8 +106,8 @@ jobs:
         run: |
           cmake -S native -B native/build/linux-x64 -G Ninja -DCMAKE_BUILD_TYPE=Release
           cmake --build native/build/linux-x64
-          mkdir -p src/DiffEngineViewer/runtimes/linux-x64/native
-          cp native/build/linux-x64/libdiffengine_viewer.so src/DiffEngineViewer/runtimes/linux-x64/native/
+          mkdir -p src/DiffEngineViewer.Linux/runtimes/linux-x64/native
+          cp native/build/linux-x64/libdiffengine_viewer.so src/DiffEngineViewer.Linux/runtimes/linux-x64/native/
 
       # Release-NotWindows drops the WinForms tray and its tests from the solution.
       - name: Build
@@ -130,6 +132,17 @@ jobs:
           dotnet test src/DiffEngineViewer.Tests/DiffEngineViewer.Tests.csproj
           --configuration Release --no-build --no-restore
 
+      # No xvfb and no GL flags: deview_capture on this platform draws into a bitmap context of its
+      # own making, so it needs neither a window nor a window server. Determinism is pinned inside
+      # that call rather than by the environment.
+      - name: Pixel snapshots
+        if: runner.os == 'macOS'
+        env:
+          DIFFENGINE_VIEWER_PIXEL_TESTS: 'true'
+        run: >
+          dotnet test src/DiffEngineViewer.Tests/DiffEngineViewer.Tests.csproj
+          --configuration Release --no-build --no-restore
+
       - name: Upload received on failure
         if: failure()
         uses: actions/upload-artifact@v4
@@ -139,10 +152,10 @@ jobs:
           if-no-files-found: ignore
           retention-days: 14
 
-  # The jobs above only ever load the x64 natives: the Linux one rebuilds its own from source, and
-  # Windows never P/Invokes because the pixel tests are Linux gated. This job exists so the other
-  # four committed binaries are actually loaded somewhere, which is what catches a wrong
-  # architecture, a file corrupted by a text mode checkout, or an unsatisfied runtime dependency.
+  # The jobs above only ever load the x64 natives, and the Linux one rebuilds its own from source.
+  # This job exists so the arm64 binaries are actually loaded somewhere, which is what catches a
+  # wrong architecture, a file corrupted by a text mode checkout, or an unsatisfied runtime
+  # dependency.
   #
   # It runs DiffEngineViewer.Tests rather than the whole suite: that is where the native smoke test
   # lives, it takes seconds, and it gives the screen and IPC tests some cross architecture coverage
@@ -159,12 +172,12 @@ jobs:
           # targeting one now sits queued indefinitely. Both macOS RIDs ship the same universal
           # dylib, so loading it here covers the arm64 slice and the step below checks that the
           # x86_64 slice is present.
+          #
+          # No Windows entry either, since that head renders with WinForms and loads nothing.
           - rid: osx-arm64
             os: macos-14
           - rid: linux-arm64
             os: ubuntu-24.04-arm
-          - rid: win-arm64
-            os: windows-11-arm
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -189,7 +202,7 @@ jobs:
         if: matrix.rid == 'osx-arm64'
         run: |
           for rid in osx-arm64 osx-x64; do
-            dylib="src/DiffEngineViewer/runtimes/$rid/native/libdiffengine_viewer.dylib"
+            dylib="src/DiffEngineViewer.Mac/runtimes/$rid/native/libdiffengine_viewer.dylib"
             archs=$(lipo -archs "$dylib")
             echo "$rid: $archs"
             for arch in x86_64 arm64; do

claude.md

@@ -46,30 +46,40 @@ DiffEngine is a library that manages launching and cleanup of diff tools for sna
 - `ResolvedTool` - A diff tool that was found on the system with its resolved executable path.
 - `BuildServerDetector` - Detects CI/build server environments to disable diff tool launching.
 
-**DiffEngineViewer (`src/DiffEngineViewer/`):**
-- Cross platform GUI diff tool: Dear ImGui rendered through raylib. Reviews inline snapshots and
-  plain two-file diffs.
+**DiffEngineViewer (`src/DiffEngineViewer/` plus three heads):**
+- Cross platform GUI diff tool. Reviews inline snapshots and plain two-file diffs.
+- `src/DiffEngineViewer/` is a **library** (`DiffEngineViewer.Core.dll`) holding everything that is
+  not a renderer. `src/DiffEngineViewer.{Windows,Mac,Linux}/` are thin `Exe` heads, one package
+  each, all named `DiffEngineViewer` so the launcher can resolve the executable by name.
+- One package per OS rather than one portable one, because WinForms must be named as a framework
+  dependency and such a package cannot start on macOS or Linux.
 - Bundled inside DiffEngine.nupkg under `tools/viewer/{rid}/`, so inline snapshots work with no
-  extra install. Also shipped standalone as the `DiffEngineViewer` dotnet tool.
+  extra install. `DiffEngine.csproj` maps each RID to the head that renders on it.
 - `ViewerSession` is a pure state machine over an immutable `SessionState`. `ScreenBuilder`
   projects that into a `Screen` (already sliced to the visible rows), which `AsciiRenderer` draws
-  as text and the native shim draws as pixels. Both renderers consume the identical structure,
-  which is what makes the text snapshots meaningful.
+  as text and each `IViewerWindow` draws as pixels. Every renderer consumes the identical
+  structure, which is what makes the text snapshots meaningful and keeps three renderers honest.
+- `ViewerProgram.Run(args, OpenWindow)` owns the loop for all heads. A head is a `Main` that
+  chooses a renderer; nothing else about the app is per platform.
+- Windows renders with **WinForms** and loads no native library. It is pumped through
+  `Application.DoEvents` rather than `Application.Run`, so the shared loop stays shared.
+- macOS renders with **AppKit and Core Text** (`native/swift/`), Linux with **raylib and Dear
+  ImGui** (`native/`). Both implement the same C ABI, so the managed interop layer is identical.
 - Does **not** reference DiffEngine. It links `Inline/*.cs` and `Tray/TrayDetector.cs` as source,
-  because DiffEngine publishes and embeds the viewer and a reference back would be a cycle.
+  because DiffEngine publishes and embeds the heads and a reference back would be a cycle.
 - Single instance by socket bind on 3493 (`DiffEngine_ViewerPort`): whoever binds owns the window,
   and a process that fails to bind forwards its patch and exits.
 
-**Native shim (`native/`):**
+**Native shim (`native/`), used by the Mac and Linux heads only:**
 - `raylib` and `imgui` are fetched by CMake (`FetchContent`), pinned by tag in
   `native/CMakeLists.txt`. Deliberately not submodules: nothing in a normal `dotnet build` touches
   this folder, so a recursive clone on every checkout would serve a path almost nobody takes.
 - Building it needs CMake 3.24+, a C++17 compiler and network access. Contributors do not need
   any of that, because the binaries are committed.
-- `native/src/deview.cpp` is a renderer for the `Screen` model, not an ImGui binding: ~12 exports
+- `native/src/deview.cpp` is a renderer for the `Screen` model, not an ImGui binding: eight exports
   taking one flat blittable frame description. The ABI is `native/include/deview.h`; bump
-  `DEVIEW_VERSION` whenever the structs change.
-- Built binaries are **committed** to `src/DiffEngineViewer/runtimes/{rid}/native/`, so a plain
+  `DEVIEW_VERSION` whenever the structs change **or a field changes meaning**.
+- Built binaries are **committed** to `src/DiffEngineViewer.{Linux,Mac}/runtimes/{rid}/native/`, so a plain
   `dotnet build` produces a shippable package and contributors never need CMake. Regenerate them
   with the `build-native` GitHub workflow, which opens a PR.
 
@@ -82,6 +92,16 @@ DiffEngine is a library that manages launching and cleanup of diff tools for sna
   every platform rather than a Windows-only copy that can drift.
 - Allows accepting/discarding diffs from system tray
 
+**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
+  tray package, an incomplete bundled head.
+- Exists because package content is assembled by several unrelated MSBuild mechanisms and nothing
+  else asserts the result. The failure mode it was written for is stale build output: `PackAsTool`
+  packages the publish directory wholesale, and MSBuild never removes a file that stopped being
+  produced, so anything a discarded experiment left in `bin` keeps shipping.
+- Windows only, and skipped entirely when no packages were produced, which is every Debug build.
+
 ### Adding a New Diff Tool
 
 1. Add enum value to `DiffTool.cs`

docs/diff-tool.md

@@ -284,8 +284,8 @@ DiffTools.UseOrder(DiffTool.DiffEngineViewer);
 #### Notes:
 
  * Bundled inside the DiffEngine package, so it needs no install
- * Also available standalone via `dotnet tool install -g DiffEngineViewer`
- * Cross platform: Windows, macOS and Linux
+ * Also available standalone as `DiffEngineViewer.Windows`, `.Mac` or `.Linux`
+ * Cross platform: WinForms on Windows, Dear ImGui through raylib elsewhere
 
 #### Windows settings:
 

docs/mdsource/viewer.source.md

@@ -8,18 +8,34 @@ source file.
 Unlike every other entry in the [tool list](/docs/diff-tool.md), it does not need to be installed.
 A copy ships inside the DiffEngine package, so it is always present.
 
-The UI is [Dear ImGui](https://github.com/ocornut/imgui) rendered through
-[raylib](https://github.com/raysan5/raylib).
+The renderer is native to each platform:
+
+| Platform | Renderer |
+| --- | --- |
+| Windows | WinForms |
+| macOS | AppKit and Core Text |
+| Linux | [Dear ImGui](https://github.com/ocornut/imgui) through [raylib](https://github.com/raysan5/raylib) |
+
+All three draw the same screen model, and the layout, scrolling and keyboard handling are shared,
+so the only difference is how the pixels get there.
 
 
 ## NuGet
 
- * https://www.nuget.org/packages/DiffEngineViewer
+ * https://www.nuget.org/packages/DiffEngineViewer.Windows
+ * https://www.nuget.org/packages/DiffEngineViewer.Mac
+ * https://www.nuget.org/packages/DiffEngineViewer.Linux
 
 Only needed to use the viewer outside a project that references DiffEngine, since DiffEngine
 already bundles it.
 
-`dotnet tool install -g DiffEngineViewer`
+```
+dotnet tool install -g DiffEngineViewer.Windows
+```
+
+One package per operating system rather than one for all of them, because WinForms has to be named
+as a framework dependency and a package that names it cannot start anywhere else. The copy bundled
+in DiffEngine is unaffected: it is published per RID and resolved by directory.
 
 
 ## Usage
@@ -80,5 +96,5 @@ continuous testing and AI CLIs.
 ## Platforms
 
 Ships for `win-x64`, `win-arm64`, `linux-x64`, `linux-arm64`, `osx-x64` and `osx-arm64`. On a
-platform with no matching binary, resolution falls through to a globally installed
+platform with no matching build, resolution falls through to a globally installed
 DiffEngineViewer tool, and then to whatever other diff tool is available.