Companion app

The companion app is a cross-platform desktop application (Windows, macOS, Linux - built with Avalonia) that shows a live preview of a document while you develop it. It is a development tool: it never ships with your application.

Download

Platform	Download
Windows x64	papyra-companion.exe
Windows ARM64	papyra-companion.exe
macOS Apple Silicon	Papyra Companion.app
macOS Intel	Papyra Companion.app
Linux x64	papyra-companion
Linux ARM64	papyra-companion

These are self-contained, single-file builds of the latest main - no .NET runtime required. They’re unsigned: macOS Gatekeeper will refuse a plain double-click, so right-click the .app and choose Open the first time (or xattr -d com.apple.quarantine "Papyra Companion.app"); on Linux, chmod +x papyra-companion after downloading.

Start it, then push documents

dotnet run --project Papyra.Companion     # or start the installed app

From your code:

using Papyra.Companion;
using Papyra.Core;

var document = Document.Create(doc => doc
    .PageSize(PageSize.A4)
    .Paragraph(p => p.Text("Hello")));

document.ShowInCompanion();

document.ShowInCompanion() renders the document to PDF and pushes it to the app on 127.0.0.1:12500. Re-running the program pushes a new tab to the open window - combine it with hot reload:

dotnet watch run --project YourApp

Ctrl+Click works because Document.Create records each builder call’s source location by default. For high-volume batch rendering where a document is never previewed, skip that bookkeeping with Document.Create(configure, captureSource: false).

What you get

A tab per push - every call to ShowInCompanion() opens its own tab, labeled with the document’s title and the time it arrived, so re-running your program repeatedly (e.g. under dotnet watch) builds up a history you can flip back through instead of only ever seeing the latest version. Close tabs you no longer need with the ✕ on their label.
Rendered pages with zoom (0.5×–3×)
Structure tree with bidirectional highlighting - click a node to highlight the element on the page, click the page to select the node
Click-to-source - Ctrl+Click (macOS: also Cmd+Click) an element to open the exact builder call in Rider or VS Code (Visual Studio opens the file without line navigation). This works because Document.Create captures the source location of every builder call by default.
Layout issue detection - fixed widths wider than the page, text wider than its cell, elements taller than a page, and content clipped at page breaks appear as red overlays, ⚠ badges in the tree, and a clickable issues panel
Inspection tools - a status bar with cursor position in points (click to copy), hovered element kind and size, a drag-to-measure ruler, and a search box for the structure tree
Snap mode - toggle “Snap” in the toolbar (or press S) and the ruler and coordinate picker lock onto element corners and edge midpoints: measure a table cell edge-to-edge or copy an exact corner coordinate without pixel hunting. A teal crosshair marks the active snap target, and snapped status-bar readings carry a ⌖ prefix. The setting persists across sessions.

Auto-start and configuration

If no companion app is listening, the client tries to start one - from CompanionOptions.CompanionExecutablePath, the PAPYRA_COMPANION_PATH environment variable, or papyra-companion on the PATH. When all of that fails it prints a warning and returns: a missing preview never breaks your program.

The app listens on localhost only (127.0.0.1:12500); nothing is exposed to the network.

On macOS you can build a proper Papyra Companion.app bundle (dock icon included) with Papyra.Companion/build/make-macos-bundle.sh; the first launch shows macOS’s one-time local-network permission prompt.

Try it with the sample

dotnet run --project Papyra.Companion              # start the preview app
dotnet watch run --project Samples -- --companion  # push the invoice on every change
dotnet run --project Samples -- --companion-issues # a document with deliberate layout issues

Composing a document from scratch?

The companion app previews a document your code already builds - it has nothing to show until you push one. To compose a report visually and get the equivalent C# back, see the designer app, a separate desktop tool built for exactly that.