DEO Desk

Your local document-preparation and data-entry companion.

Collect pages from different folders, put them in the exact order you need, save a clean PDF, and reuse copied text without leaving your desk. DEO Desk is a native 64-bit Windows, Linux amd64, and Apple Silicon macOS application: no browser, no server, and no document upload.

Add folders → review pages → arrange the PDF → save → keep working

The desk at a glance

Workspace	What DEO Desk provides
Document collection	Add images and PDFs from multiple folders without clearing earlier work. Thin path separators keep every source visible.
Folder memory	Resume page order, rotation, selection, discard, and exported markers from a validated per-folder .desk file.
Page preparation	Preview, select, rotate, discard, reorder, and assign exact export positions from one thumbnail workspace.
PDF output	Control compression, optional printed page numbers, output names, save locations, and filename collisions.
Data entry	Keep a session clipboard history, pin reusable text across launches, and copy any entry back when needed.
Job profiles	Switch between persistent settings for different work types, starting with the protected default profile.
Local safety	Work stays on the computer; Clear is explicit, exit asks for confirmation, and source removal is recoverably archived.

Everyday workflow

1. Build the workspace. Use Open to select one or several folders in the same picker. Every chosen folder is appended beneath its own path separator, multi-page PDFs expand into individual pages, and valid saved desk work is restored automatically. Reopening a folder already present is ignored.
2. Review the material. Browse crisp background-loaded thumbnails, use the resizable preview pane, click ⛶ to fit the preview, or double-click a page for a large scrollable view.
3. Choose and arrange pages. Click, Ctrl-click, Shift-click, rubber-band, or use Ctrl+A. Blue circles show the selected pages' exact PDF order. Movement, page-number reassignment, and rotation work across every added folder.
4. Set the output. Choose a saved export name or leave default selected to enter a filename at save time. Adjust compression on the toolbar and optional printed page numbers in Settings.
5. Save and continue. Click 💾 (N), where N is the number of selected pages. Exported pages are marked in yellow but remain selectable for another PDF. Only Clear resets the workspace.
6. Reuse data-entry text. Open 📋 to copy captured text back, pause capture, or pin important entries across launches. Clear All removes both session entries and persistent pins.

Workspace controls

Control	Action
Open	Select and append one or several unique input folders
Select: ☑ / ◫ / ☐	Select all pages, only unexported pages, or no pages
Clear Desk	Remove all folders from the current view without exiting
✕	Discard every selected page without changing its source file
↺ / ↻	Rotate selected pages counter-clockwise or clockwise
|◀ / ▲ / ▼ / ▶|	Move selected pages to top, back, forward, or bottom
▣	Show or hide the preview pane on the right
⛶	Fit the active preview inside the preview pane
💾 (N)	Save the selected pages as one ordered PDF
📋	Open clipboard history, persistent pins, copy-back, pause, and clear controls
⚙	Manage job profiles, PDF/export preferences, preview behavior, and JSON presets

Right-click any thumbnail to change its selected-page number, move or rotate it, discard it, or remove its real source. Confirmed source removal moves the file into that input folder's .xpose directory so it can be recovered. Removing a PDF source also removes all of its page thumbnails from the desk.

PDF and preset behavior

• Each selected thumbnail becomes one output page, including individual pages expanded from an input PDF.
• Initial order uses natural filenames (page2 before page10) and can be changed across folders before saving.
• Compression starts at 50% and ranges from 0-90%. At 0%, unchanged JPEGs pass through without re-encoding; higher values recompress rasterized pages.
• Source-folder mode writes to a PDF subfolder beside the first selected page. Settings can instead use a persistent custom folder or ask on every export.
• Existing outputs offer Overwrite, Keep Both (name_2.pdf, name_3.pdf, ...), or Cancel.
• Save JSON Preset and Load JSON Preset transfer the editable export-name list and save-location setup.

JSON presets use the versioned deo-desk-export-preset schema. They contain export_names and save_location (mode plus custom_path) only. Loaded names are sanitized, deduplicated, and always keep default first.

Persistent job profiles

Settings is separated into Profiles, Export Names and Location, PDF Output, and Workspace View sections. It opens on the active profile. The protected default profile is created automatically; Add copies the currently displayed settings into a new named profile. Other profiles can be renamed or removed. The active profile and every profile's export names, save location, printed page numbers, compression, thumbnail size, PDF DPI, selected export name, preview visibility, and Fit to Box preference persist between launches. Window geometry remains global.

Portable JSON export presets remain deliberately smaller than job profiles, so they can transfer only naming and output-path rules without changing local view or quality preferences.

Resume folder work

DEO Desk automatically writes .deo-desk.desk inside each opened input folder. The file uses the versioned deo-desk-workspace JSON schema and stores relative page references, ordering, rotations, selection, discard markers, and exported markers. Changes are saved as you work and once more on a confirmed exit.

Before restoring anything, DEO Desk validates the schema version, every page entry, and the exact source inventory using filenames, sizes, and modification times. A missing, malformed, incompatible, or stale file is ignored without interrupting the folder load; the folder starts fresh and receives a new valid snapshot. Clear closes the current workspace but deliberately keeps these per-folder files, so opening the same unchanged folder resumes the previous desk.

Privacy and session safety

DEO Desk processes documents locally. Clipboard capture operates only while the application is running and keeps at most 100 text entries. Unpinned entries stay in memory and disappear at exit. Entries explicitly pinned by the user are saved in DEO Desk's local application preferences until unpinned or cleared. Closing the app asks for confirmation with Stay as the safe default. Clear resets the current folders, page state, and selections without closing the application.

Supported inputs

png, jpg, jpeg, pdf, webp, bmp, gif, tif, and tiff.

Install and run

Apple Silicon macOS

Use a native arm64 (or universal2) Python 3, installed from python.org or Homebrew. An Intel-only Python running through Rosetta is intentionally rejected so the app and its Qt libraries remain native Apple Silicon binaries.

From Terminal, make the launchers executable once and start the app:

chmod +x deo_desk.command build_macos.command
./deo_desk.command

deo_desk.command creates .venv-macos-arm64, installs the dependencies on first launch, and then starts the Qt app. After the chmod, it can also be double-clicked in Finder. Large dependency downloads use a 10-minute read timeout with 10 retries. On unusually slow connections, override these values with DEO_DESK_PIP_TIMEOUT and DEO_DESK_PIP_RETRIES. To open a folder immediately:

./deo_desk.command "/path/to/scans"

If a first-time download is interrupted, run ./deo_desk.command again; the existing virtual environment is reused and installation continues normally.

Build a native .app

The build must run on the Apple Silicon Mac; PyInstaller does not cross-compile macOS applications from Windows. Run:

./build_macos.command

Output: dist/DEO_Desk_<version>.app. The bundle is an arm64, windowed PyInstaller onedir app, carries the matching VERSION metadata, and is ad-hoc signed for local use. Previous outputs and build scratch are archived under .xpose/ before rebuilding. For distribution to other Macs, use an Apple Developer ID and then notarize the finished app:

./build_macos.command --codesign-identity \
  "Developer ID Application: Your Name (TEAMID)"

For a sharp Finder/Dock icon, add app_icon.icns at the project root. The build also accepts app_icon.png or the existing app_icon.ico as fallbacks.

64-bit Windows

Qt/PySide6 requires 64-bit Python. First-time setup:

py -3-64 -m venv .venv-x64
.venv-x64\Scripts\python -m pip install -r requirements.txt

Then double-click deo_desk.bat, or run:

.venv-x64\Scripts\python app.py [optional\folder\path]

Build a standalone .exe

Double-click build.bat, or run:

python build_exe.py

Output: dist/DEO_Desk_<version>.exe (bundles Qt, so the target machine does not need Python). PyInstaller uses GitHub's same-drive RUNNER_TEMP in Actions and the system temp folder locally when it shares the source drive. A cross-drive local setup falls back to ignored .xpose/build-work, avoiding PyInstaller's Windows relative-path failure. Previous outputs are archived under .xpose/. The existing app_icon.ico brands the executable and running window.

Build the Windows installer

Install Inno Setup 6, build the portable executable, then compile the installer definition:

python build_exe.py
"C:\Program Files (x86)\Inno Setup 6\ISCC.exe" setup.iss

Output: release/DEO_Desk_Setup_<version>_x64.exe. It installs per-user under %LOCALAPPDATA%\Programs\DEO Desk, creates a Start Menu shortcut, and optionally creates a desktop shortcut without requiring administrator privileges.

Linux amd64

Install 64-bit Python 3, its virtual-environment package, and the Qt runtime libraries. On Ubuntu 22.04 or newer:

sudo apt-get install python3-venv libegl1 libxcb-cursor0 libxkbcommon-x11-0
python3 build_exe.py

The build creates .venv-linux-x64 and outputs the standalone executable at dist/DEO_Desk_<version>. Tag releases package it as DEO_Desk_<version>_Linux_amd64.tar.gz, preserving its execute permission.

Tests and releases

Run all automated tests with:

python -m unittest discover -s tests -t . -v

CI runs the suite on Linux and Windows. Pushing a tag such as v0.3.1 starts the release workflow, which requires the tag to match VERSION, reruns the tests, builds the x64 Windows portable executable and Inno Setup installer, a native Apple Silicon macOS application ZIP, and a Linux amd64 archive. It generates SHA-256 checksums for all four artifacts and publishes them using that version's CHANGELOG.md section. The macOS bundle is ad-hoc signed but not Apple-notarized, so another Mac may require its normal Gatekeeper override on first launch. See docs/releasing.md for the release checklist.

Layout

File	Purpose
app.py	Qt window: toolbar, thumbnail grid, preview pane, export flow
desk_state.py	Validated per-folder .desk autosave and restoration
input_sources.py	Natural input ordering and image/PDF-page references
export_presets.py	Versioned JSON export-name and save-location presets
profiles.py	Validated persistent job profiles and default preferences
image_io.py	Image decoding and PyMuPDF-backed PDF-page rendering
thumbnails.py	Background (QThreadPool) thumbnail decoding
pdf_export.py	Ordered rotation/compression/page-number PDF export
build_exe.py	Windows .exe, Linux amd64, and Apple Silicon .app builds
setup.iss	Per-user x64 Windows installer definition
tests/	Unit, Qt behavior, PDF, image, build, and release checks
deo_desk.command	Native arm64 macOS source launcher and first-run setup
build_macos.command	Double-clickable native arm64 macOS build launcher
deo_desk.bat	Windows source launcher via .venv-x64