If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/pojala/electrino shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Stale — last commit 3y ago

• 7 active contributors
• Distributed ownership (top contributor 44% of recent commits)
• MIT licensed
• Tests present
• ⚠ Stale — last commit 3y ago
• ⚠ No CI workflows detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live pojala/electrino repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/pojala/electrino.

What it runs against: a local clone of pojala/electrino — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in pojala/electrino | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 1279 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of pojala/electrino. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/pojala/electrino.git
#   cd electrino
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of pojala/electrino and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "pojala/electrino(\\.git)?\\b" \\
  && ok "origin remote is pojala/electrino" \\
  || miss "origin remote is not pojala/electrino (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "Electrino/macOS/Electrino/ENOJavaScriptApp.m" \\
  && ok "Electrino/macOS/Electrino/ENOJavaScriptApp.m" \\
  || miss "missing critical file: Electrino/macOS/Electrino/ENOJavaScriptApp.m"
test -f "Electrino/macOS/Electrino/AppDelegate.m" \\
  && ok "Electrino/macOS/Electrino/AppDelegate.m" \\
  || miss "missing critical file: Electrino/macOS/Electrino/AppDelegate.m"
test -f "Electrino/macOS/Electrino/ENOJSApp.m" \\
  && ok "Electrino/macOS/Electrino/ENOJSApp.m" \\
  || miss "missing critical file: Electrino/macOS/Electrino/ENOJSApp.m"
test -f "Electrino/macOS/Electrino/ENOJSIPCMain.m" \\
  && ok "Electrino/macOS/Electrino/ENOJSIPCMain.m" \\
  || miss "missing critical file: Electrino/macOS/Electrino/ENOJSIPCMain.m"
test -f "Electrino/macOS/Electrino/ENOJSBrowserWindow.m" \\
  && ok "Electrino/macOS/Electrino/ENOJSBrowserWindow.m" \\
  || miss "missing critical file: Electrino/macOS/Electrino/ENOJSBrowserWindow.m"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 1279 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1249d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/pojala/electrino"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Electrino is a lightweight desktop application runtime that uses the system's native web browser engine (WebKit on macOS, EdgeHTML on Windows) to run web-based apps, achieving a 115 MB reduction compared to Electron (167 kB vs 115 MB for Hello World). It implements a minimal Electron-compatible API surface (app, BrowserWindow, ipcMain, Tray, nativeImage) written in Objective-C for macOS and C# for Windows, enabling developers to ship small, platform-native desktop apps without bundling a full Chromium engine. Platform-specific monolithic structure: Electrino/macOS/ contains all Objective-C source files (ENOJSBrowserWindow.m, ENOJSIPCMain.m, etc.) implementing the API bridge to macOS WebKit, while a parallel Windows implementation would live elsewhere (not shown in file list). Test applications reside in Electrino/test-app/ and Electrino/test-tray/ with minimal package.json configurations, demonstrating the expected app structure for developers.

Developers building small, single-purpose desktop utilities and menu bar applications (like Stretchly) who want Electron's JavaScript/web technology convenience but need dramatically smaller binary sizes and native OS integration; maintainers of lightweight tools who prioritize distribution size over comprehensive API coverage.

Experimental and early-stage: this is an openly acknowledged experimental project by Pauli Ojala with limited cross-platform support (macOS and Windows 10 only). No evidence of published releases, CI/CD pipelines, or automated tests in the file structure. The presence of personal xcuserdata folders and individual user schemes suggests this is still in prototype phase with limited community contributions.

High risk for production use: single maintainer (Pauli Ojala) with secondary contact (Amila Welihinda), no visible test suite or CI automation, incomplete feature coverage (commented roadmap items like 'Support require() calls' and 'Add Node.js backend'), and only partial platform support (macOS and Windows 10, no Linux). The Objective-C and C# split across platforms increases maintenance burden and likelihood of behavioral divergence between macOS and Windows implementations.

The repository appears to be in hibernation—no recent activity visible from the file structure alone. The project roadmap explicitly mentions examining Stretchly app APIs as a reference implementation and notes that Electron is recommended for larger productivity apps, suggesting the author has already defined the target use case boundaries. No active pull requests or ongoing feature implementation is apparent from the provided data.

git clone https://github.com/pojala/electrino.git
cd electrino/Electrino/macOS
open Electrino.xcodeproj

Then build via Xcode (macOS development requires Xcode 10+). For Windows, a separate Visual Studio setup would be needed (not shown in files). Test the example app at Electrino/test-app/ after building the runtime.

Daily commands: macOS: Open Electrino/macOS/Electrino.xcodeproj in Xcode and press Cmd+R to build and run. The test apps (test-app/main.js, test-tray/main.js) serve as entry points—they load HTML via WebView and communicate with native code. Windows: Visual Studio project setup required (not detailed in visible files). No npm start or webpack dev server involved; this is a native app that loads local HTML/JS directly.

• Electrino/macOS/Electrino/ENOJavaScriptApp.m — Core macOS runtime that bootstraps the JavaScript app environment and bridges native APIs to JavaScript
• Electrino/macOS/Electrino/AppDelegate.m — macOS application entry point that initializes the Electrino runtime and manages app lifecycle
• Electrino/macOS/Electrino/ENOJSApp.m — JavaScript-exposed app API module providing fundamental application control (quit, version, etc.)
• Electrino/macOS/Electrino/ENOJSIPCMain.m — Inter-process communication main module enabling message passing between JavaScript frontend and native backend
• Electrino/macOS/Electrino/ENOJSBrowserWindow.m — BrowserWindow implementation for macOS that manages native windows hosting web content
• Electrino/win10/Electrino/App.xaml.cs — Windows 10 application entry point for the Electrino runtime on Windows platform
• Electrino/win10/Electrino/JS/JSApp.cs — Windows JavaScript API bindings for app functionality, mirroring macOS ENOJSApp

Add a new API module to macOS

1. Create header file following naming convention ENOJSModuleName.h with property declarations (Electrino/macOS/Electrino/ENOJSApp.h (as template))
2. Create implementation file ENOJSModuleName.m with JSExport protocol methods (Electrino/macOS/Electrino/ENOJSApp.m (as template))
3. Register module in ENOJavaScriptApp.m by instantiating and exporting via JSContext (Electrino/macOS/Electrino/ENOJavaScriptApp.m)
4. Test the module using the test app main.js by requiring and calling methods (Electrino/test-app/main.js)

Add a new API module to Windows

1. Create new module class inheriting from JSModule following naming JSModuleName.cs pattern (Electrino/win10/Electrino/JS/JSApp.cs (as template))
2. Implement constructor accepting JavaScriptContext and define API methods as public (Electrino/win10/Electrino/JS/JSApp.cs (as template))
3. Register module in JavaScriptApp.cs by instantiating and setting on JS context object (Electrino/win10/Electrino/JavaScriptApp.cs)
4. Handle type conversion using JavaScriptValueToJTokenConverter for return values (Electrino/win10/Electrino/JS/JavaScriptValueToJTokenConverter.cs)

Create a new test application

1. Create new folder under Electrino/ with name following test-* pattern (Electrino/test-app/ (as template))
2. Create package.json with name, version, and main entry pointing to main.js (Electrino/test-app/package.json (as template))
3. Create main.js requiring electrino modules and creating BrowserWindow instances (Electrino/test-app/main.js (as template))
4. Create index.html with frontend UI that communicates via ipcRenderer messages (Electrino/test-app/index.html (as template))

• Objective-C (macOS) / C# (Windows) — Direct access to native APIs (NSWindow, WebView2, UWP) for minimal binary overhead and tight OS integration
• WebKit/WKWebView (macOS) and WebView2 (Windows) — Use system browser engines already present on OS to avoid bundling Chromium, achieving 167 kB vs 115 MB Electron overhead
• JavaScriptCore (macOS) / Chakra (Windows) — Lightweight OS-provided JavaScript engines for executing user app code without bundling Node.js runtime
• Xcode project structure (macOS) / Visual Studio solution (Windows) — Standard native project layouts for each platform enable platform-native development workflows and tooling

• Minimal API surface (app, BrowserWindow, ipcMain, Tray, nativeImage only)

  • Why: Reduces development effort and keeps binary size tiny
  • Consequence: Apps cannot use full Electron API; requires porting/workarounds for advanced features; no Node.js backend available yet

• Separate platform implementations (macOS Objective-C, Windows C#)

  • Why: Leverages each platform's native toolchain and frameworks
  • Consequence: Higher maintenance burden; feature parity requires dual implementation; no code sharing between platforms

• No built-in Node.js runtime

  • Why: Saves ~40 MB of app size
  • Consequence: Cannot use npm packages; backend logic must be implemented in Objective-C/C# or through IPC to external services

• Direct system WebView integration

  • Why: Automatic OS updates and native rendering performance
  • Consequence: Less control over renderer behavior; WebView bugs affect app; OS

No explicit build instructions or environment setup documentation visible—Xcode version requirements and macOS deployment target are locked in the .pbxproj file, not documented. The Objective-C code assumes developers understand WKWebView API and macOS app lifecycle. No CocoaPods/SPM dependency management visible, suggesting all native code is inline or manually managed. Windows and macOS implementations are maintained separately with no shared codebase, creating synchronization risk. The test apps use bare require('electrino') which implies a custom module resolution—how the runtime injects itself into the JavaScript context is not obviously documented. Single user workspace files (xcuserdata/pauli.xcuserdatad) are committed, which may cause merge conflicts.

• Inter-Process Communication (IPC) via WKScriptMessageHandler — Electrino's entire architecture hinges on bidirectional messaging between the JavaScript thread (WKWebView) and Objective-C native thread—understanding this pattern is essential to adding any new API
• WebView Engine Abstraction — Electrino explicitly uses the system's native WebKit (macOS) and EdgeHTML (Windows) rather than bundling Chromium; understanding this architectural choice and its constraints (no Chromium APIs, system engine versioning) is critical
• Electron API Surface Compatibility Layer — Electrino implements a subset of Electron's API (app, BrowserWindow, ipcMain, Tray, nativeImage) as a facade—developers coming from Electron need to understand which APIs are available and how they differ
• Native Image Representation (ICO, PNG, ICNS formats) — ENOJSNativeImage.m/h abstracts cross-platform image handling for tray icons and app icons; understanding macOS NSImage and Windows image APIs is needed for icon/tray feature development
• Objective-C Bridge Pattern — Electrino's Objective-C classes expose methods and properties to JavaScript via the WKScriptMessageHandler bridge—contributors must understand this pattern to add new native capabilities
• Single-Origin Policy and Web Security in WebView — Running local HTML/CSS/JS in a system WebView requires careful handling of CORS, content security policies, and file:// URL restrictions—developers must avoid security pitfalls when packaging apps
• Application Bundle Structure (macOS .app format) — Electrino-built macOS apps follow the standard .app bundle structure (Contents/MacOS/Resources/); understanding how assets, code, and metadata are organized is essential for packaging and distribution

• electron/electron — The primary inspiration and benchmark—Electrino explicitly aims to provide a minimal, lightweight alternative to Electron's comprehensive but heavyweight runtime
• tauri/tauri — Modern alternative that uses system WebView (WKWebView, WebKit2GTK, WebView2) similar to Electrino but with Rust backend and cross-platform support including Linux
• nodegui/nodegui — Uses native widgets (Qt) instead of WebView but targets similar small desktop app use case with Node.js + JavaScript
• hovancik/stretchly — Real-world Electron app explicitly mentioned in Electrino's roadmap as a candidate for porting to demonstrate API coverage adequacy
• WebKit/WebKit — Core dependency on macOS; understanding WKWebView API is essential for contributing to Electrino's native layer

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Implement cross-platform require() resolution for test-app and test-tray

The README explicitly lists 'Support require() calls' as an incomplete feature. The test-app and test-tray both have package.json files but likely lack proper module loading. Implementing require() support would enable developers to use npm packages in Electrino apps, significantly improving its viability as an Electron alternative. This requires updating ENOJavaScriptApp.m (macOS) and App.xaml.cs (Windows 10) to resolve and execute CommonJS modules.

• [ ] Add require() hook in Electrino/macOS/Electrino/ENOJavaScriptApp.m that intercepts require() calls from the JS context
• [ ] Implement module resolution logic (check node_modules, handle relative paths) in a new helper class like ENOModuleResolver.m
• [ ] Add equivalent require() support to Electrino/win10/Electrino/App.xaml.cs for Windows 10 parity
• [ ] Update Electrino/test-app/main.js and Electrino/test-tray/main.js to verify require() works with a simple npm package
• [ ] Add test cases validating require() resolution for relative paths, node_modules packages, and built-in modules

Add comprehensive API documentation for ENOJSBrowserWindow, ENOJSIPCMain, and other public classes

The repo contains many implemented ENO* classes (ENOJSBrowserWindow, ENOJSIPCMain, ENOJSTray, ENOJSProcess, etc.) but lacks API documentation explaining what methods are available and how to use them. New contributors and users can't understand the surface area of Electrino's API. Creating a docs/API.md file with method signatures and examples would directly enable developers to build more complex apps.

• [ ] Audit all ENO*.m and ENO*.h files in Electrino/macOS/Electrino/ to extract public methods (ENOJSBrowserWindow.m, ENOJSIPCMain.m, ENOJSTray.m, ENOJSProcess.m, ENOJSConsole.m, ENOJSNativeImage.m, ENOJSUrl.m, ENOJSPath.m)
• [ ] Create docs/API.md with sections for each class, listing method signatures, parameter types, and return values
• [ ] For each API, add a practical example showing usage (e.g., creating a BrowserWindow, sending IPC messages, creating a tray icon)
• [ ] Cross-reference the macOS implementations with Electrino/win10/Electrino equivalents to note platform differences

Add GitHub Actions CI workflow to build and test both macOS and Windows 10 versions

The repo has separate macOS (.xcodeproj) and Windows 10 (.csproj, .sln) implementations but lacks automated testing infrastructure. Without CI, contributors can't verify their changes work on both platforms before submitting PRs, increasing review burden and risk of platform-specific regressions. Adding a GitHub Actions workflow that builds both versions and runs test-app would catch integration issues early.

• [ ] Create .github/workflows/build-macos.yml that checks out the repo, sets up Xcode, builds Electrino/macOS/Electrino.xcodeproj, and verifies the output binary exists
• [ ] Create .github/workflows/build-windows.yml that checks out the repo, sets up .NET/Visual Studio build tools, builds Electrino/win10/Electrino.sln, and verifies the output package
• [ ] Add a .github/workflows/test-apps.yml that builds both platforms, then launches Electrino/test-app and Electrino/test-tray with a simple automated check (e.g., verify window appears or IPC message is received)
• [ ] Update README.md with a build status badge and instructions for running CI locally

• Write automated test suite for ENOJSBrowserWindow.m window creation and lifecycle (open, close, minimize, maximize, setTitle) since no test files are visible—this would prevent regressions as new contributors modify window handling
• Document the exact message format for IPC calls between JavaScript and Objective-C in ENOJSIPCMain.m—currently there is no spec visible; creating a markdown file in docs/ with examples would unblock new contributors trying to add APIs
• Implement or stub out the Windows C# equivalents for all Objective-C ENOJSxxx classes (at least method signatures) so contributors can see which APIs are missing parity between platforms

• High · Potential Unvalidated IPC Communication — Electrino/macOS/Electrino/ENOJSIPCMain.h and ENOJSIPCMain.m. The codebase includes IPC (Inter-Process Communication) modules (ENOJSIPCMain.h/m) that bridge JavaScript and native code. Without explicit validation of IPC messages, there is a risk of arbitrary code execution or privilege escalation if malicious scripts can trigger native function calls. Fix: Implement strict validation and sanitization of all IPC messages. Use a whitelist-based approach for allowed IPC calls. Verify message origins and implement rate limiting for IPC requests.
• High · Unsafe WebView Integration — Electrino/macOS/Electrino/ (WebView-related components). The README mentions 'Integrate WebView' as a core feature. WebViews can be vulnerable to XSS attacks if they load untrusted content without proper sandboxing or content security policies. The integration with browser engines requires careful handling of content loaded from various sources. Fix: Implement Content Security Policy (CSP) headers, disable unsafe inline scripts, validate and sanitize all loaded content, and ensure proper sandboxing of WebView contexts. Use the browser engine's security features.
• High · Unprotected Native API Exposure — Electrino/macOS/Electrino/ENOJSX*.m files (Process, Path, NativeImage, Tray, Url, etc.). Multiple modules expose native APIs to JavaScript (ENOJSProcess.m, ENOJSPath.m, ENOJSNativeImage.m, ENOJSTray.m, ENOJSUrl.m). These provide direct access to system resources. Without proper access controls, malicious or compromised scripts could exploit these APIs for unauthorized system access. Fix: Implement capability-based security model. Require explicit user permissions before granting access to sensitive APIs. Log all API calls for monitoring. Implement rate limiting and resource quotas.
• Medium · Missing Input Validation on File Paths — Electrino/macOS/Electrino/ENOJSPath.h and ENOJSPath.m. The ENOJSPath module handles file path operations. Path traversal attacks using sequences like '../' could potentially allow access to unauthorized files if input is not properly validated and normalized. Fix: Implement strict path validation using a whitelist of allowed directories. Use realpath() or equivalent to resolve symlinks and canonicalize paths. Prevent directory traversal sequences.
• Medium · Process Execution Without Validation — Electrino/macOS/Electrino/ENOJSProcess.h and ENOJSProcess.m. The ENOJSProcess module allows spawning and controlling processes. If user input is not properly sanitized before being passed to process execution functions, command injection attacks are possible. Fix: Avoid shell execution; use direct process spawning with separate arguments array. Never concatenate user input into command strings. Implement a whitelist of allowed programs to execute.
• Medium · URL Handling and Protocol Support — Electrino/macOS/Electrino/ENOJSUrl.h and ENOJSUrl.m. The ENOJSUrl module handles URL parsing and manipulation. Improper URL validation could allow protocol confusion attacks (e.g., javascript:, file:// URIs) or injection of malicious URLs. Fix: Implement strict URL validation with a whitelist of allowed protocols (http, https only). Properly parse and validate all URL components. Prevent javascript: and file:// protocol handlers unless explicitly required.
• Medium · Xcode User Data in Repository — .gitignore, Electrino/macOS/Electrino.xcodeproj/xcuserdata/, Electrino/macOS/Electrino.xcodeproj/project.xcworkspace/xcuserdata/. The repository contains Xcode user data files (.xcuserdatad, UserInterfaceState.xcuserstate, Breakpoints files). These files may contain sensitive information and should not be version controlled. Fix: Add .xcuserdatad, UserInterfaceState.xcuserstate, and xcuserdata/ to .gitignore. Remove these files from version control history using git

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.