# Why?

Positron is built as a lightweight, secure alternative to Electron. Below is a detailed breakdown of how Positron compares to Electron across key architectural and performance metrics.

#### Comparison Table

| Metric                  | Electron                                                              | Positron                                                                                |
| ----------------------- | --------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| **Render Engine**       | Chromium (bundled in every app)                                       | System-native viewports (WebKit/WKWebView on macOS, WebView2 on Windows)                |
| **Process Model**       | Multi-process tree (Main, Renderers, GPU, Network, Utility processes) | Dual-process layout (Single native Swift/C# UI runtime + Background Node.js controller) |
| **Minimum Bundle Size** | \~100MB+ (compressed), \~300MB+ (extracted)                           | **\~60MB - 100MB** (depending on bundled assets and compiled backend)                   |
| **Memory Footprint**    | Heavy (runs full Chromium engine processes)                           | **Lightweight** (reuses system WebKit/WebView2 instances)                               |
| **Native Extensions**   | Requires Node C++ Addons (N-API/NAN) compiled against Node headers    | **Stitched Native Extensions** written directly in Swift (macOS) or C# (Windows)        |
| **Security Isolation**  | IPC bridging to Node with complex sandbox/context-isolation setups    | **Strict separation by design**; renderer has zero direct access to Node.js APIs        |

### Core Advantages

#### **Zero Chromium Bloat**

Electron bundles the entire Chromium browser engine inside every single application you package. This is why a simple "Hello World" app in Electron starts at over 100MB on disk and consumes hundreds of megabytes of RAM. Positron drops Chromium entirely, opting instead for the host operating system's native web view components: **WebKit/WKWebView** on macOS and **Microsoft Edge WebView2** on Windows. This approach:

* Shrinks packaged app bundle sizes significantly.
* Reuses system memory, sharing loaded render engine assets directly with the OS.
* Provides a native look, feel, and performance right out of the box.

#### **Stitched Native Extensions**

In Electron, interacting with native operating system APIs requires writing Node.js C++ addons (Node-API / N-API) or loading native Node modules, which are complex to configure and compile against specific Node.js ABI versions. Positron introduces **Stitched Native Extensions**. You write platform-specific extensions directly in **Swift** (macOS) and **C#** (Windows). At build time, Positron's compiler parses these extensions and stitches their commands directly into the core runtime registry (`Registry.swift` or `Registry.cs`). This enables:

* Seamless execution of native code with zero JavaScript-to-C++ wrapper overhead.
* Direct access to Cocoa/macOS framework features (like AppleScript, system alerts, printing, or native notifications) and .NET/Windows SDK features.
* Clean separation of platform-specific code.

#### **Strict Security Isolation**

Electron has historically struggled with Remote Code Execution (RCE) vulnerabilities due to renderers having access to Node.js APIs. Even with security configurations like context isolation and sandboxing, misconfigurations can lead to severe security exploits. Positron enforces a strict sandbox by default:

* The WebView renderer has **absolutely no direct access** to the Node.js process or the underlying filesystem.
* Interaction is mediated entirely via a lightweight injected preload script that posts messages to the compiled native runtime.
* The native runtime forwards these events to the background Node.js master process via a local WebSocket connection.
* To prevent local socket hijacking or cross-origin attacks, the WebSocket connection is secured with a cryptographically random authorization token (`POSITRON_AUTH_TOKEN`) generated dynamically on application startup.

**4. Clean Process Architecture**

Electron spawns a heavy process hierarchy for every application window, leading to high process counts, CPU context-switching overhead, and elevated power consumption. Positron operates on a clean **dual-process architecture**:

1. **The Native UI Shell**: A lightweight compiled binary (Swift/Cocoa on macOS, C#/.NET on Windows) that acts as the single frontend process, managing all windows and native OS integrations.
2. **The Node.js Controller**: A background Node.js process acting as the master controller, running application logic, lifecycle events, database connections, and file system tasks.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://positronjs.gitbook.io/v1/why.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.