positron.js 1.0.0

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2026 Bryce
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,154 @@
+# Positron
+
+![Banner](./pbannerfull.png)
+
+Positron is a lightweight, cross-platform hybrid application framework designed to build desktop applications using a native compiled runtime shell (Swift/Cocoa/WebKit on macOS, and C#/.NET on Windows) driven by a Node.js main process.
+Unlike traditional resource-heavy frameworks, Positron separates the native windowing/render process from the JavaScript application state, establishing a lightweight, dual-process environment unified by a localized WebSocket IPC channel.
+
+## Architecture & Core Components
+Positron operates via a split architecture:
+1. The Node.js Master Process (index.js): Manages application lifecycles, creates windows, sets native menus, and hosts the IPC WebSocket server.
+2. The Native Runtime Process: A platform-specific, pre-compiled native binary (positron-runtime) responsible for rendering web views and implementing host OS features.
+3. IPC Router (ipc.js): A unified, asynchronous routing layer that handles bidirectional events between your web app render layers and your backend.
+
+## Features
+- Native Framework Integration: Drops specialized heavy chromium embeddings in favor of native UI viewports (WebKit on macOS, .NET Webview2 on Windows).
+- Stitched Native Extensions: Seamlessly hooks developer-created third-party plugins directly into the native build registry at compile time.
+- Production Packager: Automatically abstracts bundle constraints to output native macOS .app structures (complete with mandatory Info.plist manifests) and clean Windows application folders.
+- Zero-Config Dev Builds: Automatically detects missing platform-specific native binaries on launch and compiles them in the background.
+
+## Why Use Positron?
+
+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.
+
+| 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 |
+
+## Prerequisites
+- Node.js (v16+)
+- macOS: Xcode Command Line Tools (swiftc)
+- Windows: .NET SDK (CLI tools capable of executing `dotnet publish`)
+
+## Install
+```bash
+npm i positron.js
+```
+
+## Usage Example
+Initialize your main entry point using the exposed Window and ipc instances:
+```js
+const { Window, ipc } = require('positron.js');
+
+// Bind asynchronous IPC listeners from renderer layers
+ipc.handle('get-app-version', (payload, { reply }) => {
+  console.log('Renderer requested version details.');
+  reply({ version: '1.0.0-alpha' });
+});
+
+// Spawn a native window instance
+const mainWindow = new Window({
+  width: 1024,
+  height: 768
+});
+
+// Load web application files
+mainWindow.on("ready", () => {
+mainWindow.loadFile('public/index.html');
+mainWindow.setTitle('My First Positron App');
+})
+```
+
+## Native Extensions Configuration
+Positron allows local dependencies to plug natively into the platform-level shell compilation pipeline.
+To create a native extension, provide a custom positron property block within your extension dependency's package.json:
+```json
+{
+  "name": "positron-toast-plugin",
+  "version": "1.0.0",
+  "positron": {
+    "className": "ToastPlugin",
+    "command": "toast:show",
+    "platforms": {
+      "darwin": "src/mac/ToastPlugin.swift",
+      "win32": "src/win/ToastPlugin.cs"
+    }
+  }
+}
+```
+
+When builder.js executes, it parses your project dependencies, finds native extensions, and stitches their commands directly into the core platform registries (Registry.swift or Registry.cs).
+
+## Compilation & Packaging Pipeline
+
+### Compilation
+Triggered automatically during development if the binary is missing, or manually during pipeline compilation:
+- macOS: Compiles main.swift, the stitched Registry.swift, and extension source files into bin/positron-runtime using swiftc.
+- Windows: Invokes dotnet publish to build a single, self-contained Release profile binary output to bin/positron-runtime.exe.
+
+#### Build
+This will build (or rebuild) the binary, then exit
+```bash
+npx positron build
+```
+
+#### Dev
+This will build (or rebuild) the binary, then start the app
+```bash
+npx positron dev
+```
+
+#### Run
+This run the app without building
+```bash
+npx positron run
+```
+
+### Packaging
+This will rebuild the binary, then create a deployable version of the app
+```bash
+npx positron package [--m | --w] [--arm64 || --x64]
+```
+
+> Note: Windows supports either arm64 or x64, while macOS only supports arm64 on Apple Silicon.
+
+## IPC Protocol Specification
+Communication relies on structured JSON communication frames routed through the IPC WebSocket server.
+
+### Outbound Commands (Main Node ➔ Native Runtime)
+
+```json
+{
+  "windowId": 1,
+  "command": "loadURL",
+  "args": ["https://google.com"]
+}
+```
+
+
+### Inbound Events (Native Runtime ➔ Main Node)
+```json
+{
+  "event": "ipcMessage",
+  "windowId": 1,
+  "data": {
+    "channel": "form-submit",
+    "payload": "{\"username\":\"alice\"}"
+  }
+}
+```
+
+## Environment Flags
+- POSITRON_PACKAGED: Set to "true" inside production bundles to suppress localized development shell background re-compilation triggers.
+- POSITRON_IPC_PORT: The port that the IPC server runs on.
+
+## License
+MIT
+
+## Documentation
+Read docs [here](https://positronjs.gitbook.io/v1)

package/bin/positron.js

@@ -0,0 +1,40 @@
+#! /usr/bin/env node
+
+const { performNativeBuild } = require("../builder");
+const performPackager = require("../packager");
+const { spawn } = require("child_process");
+const [, , command] = process.argv;
+const { info, success, error } = require("../logs");
+
+switch (command) {
+  case "build":
+    info("Starting manual Positron build...");
+    const success = performNativeBuild();
+    process.exit(success ? 0 : 1);
+    break;
+
+  case "dev":
+    info("Starting Positron in development mode...");
+    performNativeBuild();
+    spawn("node", ["."], { stdio: "inherit" });
+    break;
+
+    case "run":
+    spawn("node", ["."], { stdio: "inherit" });
+    break;
+
+  case "package":
+        info("Packaging Positron application for production...");
+        const buildPassed = performNativeBuild();
+    if (!buildPassed) {
+      error("Packaging aborted due to build failures.");
+      process.exit(1);
+    }
+
+    performPackager();
+    break;
+
+  default:
+    console.log("Usage: npx positron [build | dev | run]");
+    process.exit(0);
+}

package/builder.js

@@ -0,0 +1,229 @@
+const fs = require("fs");
+const path = require("path");
+const cp = require("child_process");
+const { success, error, info } = require("./logs");
+
+const arch = process.argv.includes("--x64") ? "x64" : process.argv.includes("--arm64") ? "arm64" : process.arch;
+
+function performNativeBuild() {
+
+
+  let buildingForWindows = process.argv.includes("--windows") || process.argv.includes("--w");
+  let buildingForMac = process.argv.includes("--mac") || process.argv.includes("--m");
+
+
+  const appRoot = process.cwd(); // The developer's project folder
+  const nativeExtensionsMac = [];
+  const nativeExtensionsWindows = [];
+  
+  // 1. Discover Extensions from the developer's package.json
+  const rootPackagePath = path.join(appRoot, "package.json");
+  if (!fs.existsSync(rootPackagePath)) return false;
+
+  const rootPackage = JSON.parse(fs.readFileSync(rootPackagePath, "utf8"));
+  const dependencies = Object.keys(rootPackage.dependencies || {});
+
+  for (const dep of dependencies) {
+    const depPackagePath = path.join(appRoot, "node_modules", dep, "package.json");
+    if (fs.existsSync(depPackagePath)) {
+      const depPackage = JSON.parse(fs.readFileSync(depPackagePath, "utf8"));
+      if (depPackage.positron) {
+        const depDir = path.dirname(depPackagePath);
+
+          let missing = [];
+          if(!depPackage.positron.className) missing.push("className");
+          if(!depPackage.positron.command) missing.push("command");
+          if(!depPackage.positron.platforms) missing.push("platforms");
+          else {
+            if(!depPackage.positron.platforms.darwin) missing.push("platforms.darwin");
+            if(!depPackage.positron.platforms.win32) missing.push("platforms.win32");
+          }
+          
+          if(missing.includes("className") || missing.includes("command") || missing.includes("platforms")) {
+            warn(`[Builder] Dependency "${dep}" has an invalid positron field. Missing: ${missing.join(", ")}. Skipping native extension build for this dependency.`);
+            continue;
+          }
+        
+        if(!missing.includes("platforms.darwin")) {
+        nativeExtensionsMac.push({
+          className: depPackage.positron.className, 
+          command: depPackage.positron.command,
+          sourceFile: path.join(depDir, depPackage.positron.platforms.darwin)
+        });
+      } else {
+        warn(`[Builder] Dependency "${dep}" is missing a macOS platform source file. Skipping macOS native extension build for this dependency.`);
+      }
+      if(!missing.includes("platforms.win32")) {
+        nativeExtensionsWindows.push({
+          className: depPackage.positron.className, 
+          command: depPackage.positron.command,
+          sourceFile: path.join(depDir, depPackage.positron.platforms.win32)
+        });
+      } else {
+        warn(`[Builder] Dependency "${dep}" is missing a Windows platform source file. Skipping Windows native extension build for this dependency.`);
+      }
+      }
+    }
+  }
+
+  if(buildingForWindows == false && buildingForMac == false) {
+    if (process.platform === "win32") {
+      buildingForWindows = true;
+    } else if (process.platform === "darwin") {
+      buildingForMac = true;
+    } else {
+      error("[Builder] Unsupported platform for native build.");
+      return false;
+    }
+  }
+
+  if (buildingForMac) {
+    info(`[Builder] Stitching ${nativeExtensionsMac.length} native extensions...`);
+  
+        let registryContent = `// Auto-generated by Positron. Do not edit.\n`;
+    registryContent += `func getExtensionRegistry() -> [String: (Int, [String]) -> Void] {\n`;
+    
+    if (nativeExtensionsMac.length === 0) {
+      registryContent += `    return [:]\n`;
+    } else {
+      registryContent += `    return [\n`;
+      
+      nativeExtensionsMac.forEach((ext, index) => {
+
+         const comma = index === nativeExtensionsMac.length - 1 ? "" : ",";
+         registryContent += `        "${ext.command}": ${ext.className}.handle${comma}\n`;
+      });
+      
+      registryContent += `    ]\n`;
+    }
+    
+    registryContent += `}\n`;
+    
+    const coreMacDir = path.join(__dirname, "core", "mac");
+    fs.writeFileSync(path.join(coreMacDir, "Registry.swift"), registryContent);
+
+    info("[Builder] Compiling native binary...");
+    const outBinaryDir = path.join(appRoot, "bin");
+    if (!fs.existsSync(outBinaryDir)) fs.mkdirSync(outBinaryDir, { recursive: true });
+
+    const binaryName = "positron-runtime";
+    const extensionSources = nativeExtensionsMac.map(e => e.sourceFile);
+    
+    let addedFrameworksSet = new Set();
+
+    nativeExtensionsMac.forEach(ext => {
+      if (ext.macFrameworks && Array.isArray(ext.macFrameworks)) {
+        ext.macFrameworks.forEach(fw => {
+          addedFrameworksSet.add(fw);
+        });
+      }
+    });
+    
+    let addedFrameworksArgs = [];
+    addedFrameworksSet.forEach(fw => {
+      addedFrameworksArgs.push("-framework", fw);
+    });
+
+    try {
+      cp.execFileSync("swiftc", [
+        path.join(coreMacDir, "main.swift"),
+        path.join(coreMacDir, "Registry.swift"),
+        ...extensionSources,
+        "-o", path.join(outBinaryDir, binaryName),
+        "-framework", "Cocoa",
+        "-framework", "WebKit",
+        ...addedFrameworksArgs
+      ]);
+      success("[Builder] Native compilation successful.");
+
+          if(process.platform == "darwin") {
+      cp.execFile("chmod", ["+x", path.join(outBinaryDir, binaryName)], (err) => {
+        if (err) {
+          error("Failed to set executable permissions on native binary:", err);
+        }
+      });
+
+      try {
+        const iconPathEscaped = path.join(__dirname, "positronicon.png").replace(/"/g, '\\"');
+        const binPathEscaped = path.join(outBinaryDir, binaryName).replace(/"/g, '\\"');
+        const swiftScript = `import Cocoa; NSWorkspace.shared.setIcon(NSImage(contentsOfFile: "${iconPathEscaped}"), forFile: "${binPathEscaped}", options: [])`;
+        cp.execFileSync("swift", ["-e", swiftScript], { stdio: "ignore" });
+      } catch (err) {
+        error("Failed to set custom icon on native binary:", err);
+      }
+    }
+
+      return true;
+    } catch (err) {
+      error("[Builder] Compilation failed:", err.message);
+      return false;
+    }
+    } 
+    
+    
+     if (buildingForWindows) {
+    info(`[Builder] Stitching ${nativeExtensionsWindows.length} native Windows extensions...`);
+
+    const coreWinDir = path.join(__dirname, "core", "win");
+    const extensionsDir = path.join(coreWinDir, "extensions");
+
+    // 1. Clean and prepare a staging folder for all native extensions
+    if (fs.existsSync(extensionsDir)) fs.rmSync(extensionsDir, { recursive: true, force: true });
+    fs.mkdirSync(extensionsDir, { recursive: true });
+
+    let registryContent = `// Auto-generated by Positron. Do not edit.\n`;
+    registryContent += `using System;\nusing System.Collections.Generic;\n\n`;
+    registryContent += `namespace PositronWindows {\n`;
+    registryContent += `    public static class ExtensionRegistry {\n`;
+    registryContent += `        public static Dictionary<string, Action<int, List<string>>> GetExtensions() {\n`;
+    registryContent += `            return new Dictionary<string, Action<int, List<string>>> {\n`;
+
+    nativeExtensionsWindows.forEach((ext, index) => {
+        const comma = index === nativeExtensionsWindows.length - 1 ? "" : ",";
+        registryContent += `                { "${ext.command}", ${ext.className}.Handle }${comma}\n`;
+
+        const destFile = path.join(extensionsDir, `ext_${index}.cs`);
+        fs.copyFileSync(ext.sourceFile, destFile);
+    });
+
+    registryContent += `            };\n`;
+    registryContent += `        }\n`;
+    registryContent += `    }\n}\n`;
+
+    fs.writeFileSync(path.join(extensionsDir, "Registry.cs"), registryContent);
+
+    info("[Builder] Compiling Windows native binary via .NET CLI...");
+    const outBinaryDir = path.join(appRoot, "bin");
+    if (!fs.existsSync(outBinaryDir)) fs.mkdirSync(outBinaryDir, { recursive: true });
+
+    try {
+
+      const iconPath = path.join(appRoot, "icon.ico");
+      const dotnetArgs = [
+        "publish",
+        path.join(coreWinDir, "PositronRuntime.csproj"),
+        "-c", "Release",
+        "-r", `win-${arch}`,
+        "--self-contained", "true",
+        "-o", outBinaryDir,
+        "/p:PublishSingleFile=true",
+        "/p:IncludeNativeLibrariesForSelfContained=true"
+      ];
+      if (fs.existsSync(iconPath)) {
+        dotnetArgs.push(`/p:ApplicationIcon=${iconPath}`);
+      }
+
+      cp.execFileSync("dotnet", dotnetArgs, { stdio: "inherit" });
+      success("[Builder] Windows native compilation successful.");
+      return true;
+    } catch (err) {
+      error("[Builder] Windows compilation failed:", err.message);
+      return false;
+    }
+  }
+  
+  return false; // Unsupported platform
+ 
+}
+
+module.exports = { performNativeBuild };