PhotinoX.Native is an independent fork of tryphotino/photino.Native licensed under Apache‑2.0.
This project is not affiliated with the original Photino organization.
This fork maintains and improves the native cross-platform host for:
- Windows x64 / ARM64
- Linux x64 / ARM64
- macOS x64 / ARM64 (Universal)
PhotinoX.Native is a lightweight native desktop host for WebView-based applications. It creates and manages OS-native windows, embeds the platform WebView, owns the application message loop, and provides the interop and window-state infrastructure used by higher-level frameworks.
- Windows: Microsoft Edge WebView2 Runtime
https://learn.microsoft.com/microsoft-edge/webview2/ - macOS: WKWebView (system WebKit)
https://developer.apple.com/documentation/webkit/wkwebview/ - Linux: WebKitGTK 4.1 (runtime + dev packages)
https://webkitgtk.org/
Binaries included in this package:
| OS | Architecture | RID | Files |
|---|---|---|---|
| Windows | x64 | win-x64 |
PhotinoX.Native.dll, WebView2Loader.dll |
| Windows | ARM64 | win-arm64 |
PhotinoX.Native.dll, WebView2Loader.dll |
| Linux | x64 | linux-x64 |
PhotinoX.Native.so |
| Linux | ARM64 | linux-arm64 |
PhotinoX.Native.so |
| macOS | x64 | osx-x64 |
PhotinoX.Native.dylib (universal) |
| macOS | ARM64 | osx-arm64 |
PhotinoX.Native.dylib (universal) |
All files follow the standard NuGet runtimes/<rid>/native/ layout.
These repositories provide the managed .NET surface around the native binaries:
- PhotinoX - managed .NET wrapper around the native layer.
- PhotinoX.App - Application composition layer for PhotinoX desktop applications.
- PhotinoX.Blazor - Blazor integration for native desktop apps.
- PhotinoX.Server - optional local static-file server for SPA/static assets.
- PhotinoX.Samples - sample projects showcasing common scenarios.
This package is intended for developers building desktop applications with web-based UI frameworks such as Blazor, React, Vue, or Angular, while keeping the native host lightweight and dependency-minimal.
If you are looking for the main project, see:
https://github.com/ivanvoyager/PhotinoX
| Aspect | Photino (upstream) | PhotinoX (fork) |
|---|---|---|
| Concept / architecture | Lightweight alternative to Electron: native window + system WebViews (Windows: WebView2, macOS: WKWebView, Linux: WebKitGTK). | Same lightweight architecture, with fork-specific improvements in native stability, packaging, interop, and long-running application scenarios. |
| Native layer structure | Central Photino class mixes public API, callbacks, platform headers, platform state, and platform-specific implementation details. |
Keeps the same native foundation but separates callbacks, init parameters, options, strings, monitors, exports, and platform state into focused components, reducing cross-platform coupling. |
| Platform isolation | Platform-specific headers, fields, and methods are mixed directly into the main Photino declaration. |
Uses platform state objects (WindowsState, LinuxState, MacState) and platform-specific implementation sections to keep Windows, Linux, and macOS concerns isolated. |
| Native memory ownership | Uses pointer-based string conversion and implicit ownership across several native interop paths, including custom-scheme/resource responses. | Uses explicit native allocation/free helpers, owned PlatformString values, and non-owning Utf8String ABI inputs. String conversion and response buffers crossing the managed/native boundary now have predictable native ownership to reduce leak-prone paths in long-running applications. |
| Application / message loop model | Uses global native wait/invoke helpers around the native window/message loop. | Introduces PhotinoApplication as the native application lifetime object, with explicit run/shutdown semantics, lifecycle callbacks, check-access support, and sync/async dispatch. |
| Application dispatch API | Uses older global invoke/wait helpers without a consistent state-carrying callback ABI. | Provides application-level Invoke and BeginInvoke entry points using a state-aware callback shape (callback + state). This gives wrappers a predictable synchronous/asynchronous dispatch contract and allows explicit state passing without captured callbacks in dispatcher-facing paths. |
| Native notifications | Notifications are tied to the older window-oriented native model. | Moves native notifications to PhotinoApplication with explicit initialization, enable/disable state, and callback dispatch. |
| Window lifecycle callbacks | Provides the original window callback set. | Extends native callbacks with closed, fullscreen, unified state-change, WebView navigation, and content loading notifications for more complete window and WebView state reporting. |
| Window state model | Window state handling is spread across platform-specific callbacks and legacy minimized/maximized/fullscreen paths, which can produce transient or duplicate restored notifications. | Uses a unified native-driven PhotinoWindowState model (Normal, Minimized, Maximized, FullScreen) with StateChanged as the primary transition event. Legacy state callbacks are derived from actual state transitions, avoiding misleading Restored notifications from transient resize/native messages. |
| Startup window state | Startup minimized/maximized/fullscreen handling is platform-specific and tied to older separate state flags. | Startup state is normalized through the unified PhotinoWindowState model and applied during native construction without user-visible state callbacks. |
| Windows fullscreen handling | Fullscreen behavior follows the older platform-specific path. | Windows fullscreen is restore-aware: the previous style and placement are saved before entering fullscreen and restored when leaving fullscreen, with fullscreen transitions integrated into the unified state machine. |
| Windows WebView2 environment | WebView2 environment creation follows the older per-window initialization path. | Reuses compatible WebView2 environments and detects conflicting configuration for the same user data folder. |
| Linux dependency (WebKitGTK) | Migrated to WebKitGTK 4.1 in early 2025 (makefile updated before the 4.0.22 release). | Uses WebKitGTK 4.1 consistently across CI/scripts. |
| Linux documentation | Some upstream documentation still references older WebKitGTK 4.0 package. | README and build notes match the current WebKitGTK 4.1 toolchain. |
| RID packaging | Uses standard runtimes/<rid>/native/ layout in NuGet packages. |
Same standard RID layout; emphasis on keeping all target RIDs green in CI (win‑x64/arm64, linux‑x64/arm64, osx‑x64/arm64). |
Photino succeeded Steve Sanderson’s experimental WebWindow project, which explored native OS windows hosting web UI for .NET applications on Windows, macOS, and Linux. Photino continued this idea as an Electron-inspired open-source .NET project backed by the CODE Magazine team and the open-source community, while using the OS-provided WebView stack instead of bundling Chromium.
Upstream’s last public Photino.Native release is dated January 23, 2025 (v4.0.22). PhotinoX.Native continues the native-window model with independently maintained binaries and standard RID packaging. The fork focuses on clearer platform isolation, explicit native memory ownership, WebView navigation and content loading callbacks, unified window state tracking, state-aware dispatch APIs, and an application-oriented native message-loop model.
PhotinoX.Native builds with MSBuild on Windows and the included makefile on Linux and macOS.
Toolset note: The project targets MSVC v145 (Visual Studio 2026).
CI also uses v145.
CI: see
.github/workflows/photinox-native-win.yml(build + pack + uploadwin-x64/win-ARM64).github/workflows/build-native-unix.yml(build + pack + uploadlinux-x64/linux-arm64andosx-x64/osx-arm64)
Requirements:
- Visual Studio 2026 (includes support for MSVC Toolset v145)
- Workload: Desktop Development with C++
- WebView2 Runtime (required by the Windows backend)
- Build configurations:
Release | x64Release | ARM64
To build manually with MSVC Toolset v145:
msbuild .\Photino.Native\Photino.Native.vcxproj ^
/p:Configuration=Release ^
/p:Platform=x64 ^
/p:PlatformToolset=v145or for ARM64:
msbuild .\Photino.Native\Photino.Native.vcxproj ^
/p:Configuration=Release ^
/p:Platform=ARM64 ^
/p:PlatformToolset=v145sudo apt-get update
sudo apt-get install \
build-essential \
libgtk-3-dev \
libwebkit2gtk-4.1-dev \
libnotify-dev
make linux-x64 # or make linux-arm64Requirements:
- Xcode 15+ (macOS 14/15/16 toolchains)
- clang with Objective‑C++ support
- WKWebView available system-wide
make mac-universal- Linux Wayland: top-level window position is compositor-controlled. Move notifications and position restore are best-effort; state and size tracking remain supported.
- Linux chromeless drag/resize: native chromeless drag, resize, and titlebar double-click handling use GTK event-driven hit testing over configured drag and resize regions. The generic
BeginWindowDrag/BeginWindowResizeentry points remain no-ops on Linux because GTK/Wayland require the original trusted native pointer event.
Issues and PRs are welcome. Keep changes minimal and performance-conscious.
PhotinoX.Native is licensed under Apache‑2.0.