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/JadenGeller/Helium 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 4y ago

• 4 active contributors
• MIT licensed
• ⚠ Stale — last commit 4y ago
• ⚠ Small team — 4 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 97% of recent commits
• ⚠ No CI workflows detected
• ⚠ No test directory 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 JadenGeller/Helium repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/JadenGeller/Helium.

What it runs against: a local clone of JadenGeller/Helium — 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 JadenGeller/Helium | 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 ≤ 1584 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of JadenGeller/Helium. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/JadenGeller/Helium.git
#   cd Helium
#
# 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 JadenGeller/Helium and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "JadenGeller/Helium(\\.git)?\\b" \\
  && ok "origin remote is JadenGeller/Helium" \\
  || miss "origin remote is not JadenGeller/Helium (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 "Helium/Helium/AppDelegate.swift" \\
  && ok "Helium/Helium/AppDelegate.swift" \\
  || miss "missing critical file: Helium/Helium/AppDelegate.swift"
test -f "Helium/Helium/Window/HeliumWindow.swift" \\
  && ok "Helium/Helium/Window/HeliumWindow.swift" \\
  || miss "missing critical file: Helium/Helium/Window/HeliumWindow.swift"
test -f "Helium/Helium/Window/WebView/WebViewController.swift" \\
  && ok "Helium/Helium/Window/WebView/WebViewController.swift" \\
  || miss "missing critical file: Helium/Helium/Window/WebView/WebViewController.swift"
test -f "Helium/Helium/WindowControllerManager.swift" \\
  && ok "Helium/Helium/WindowControllerManager.swift" \\
  || miss "missing critical file: Helium/Helium/WindowControllerManager.swift"
test -f "Helium/Helium/Menu/Framework/Menu.swift" \\
  && ok "Helium/Helium/Menu/Framework/Menu.swift" \\
  || miss "missing critical file: Helium/Helium/Menu/Framework/Menu.swift"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 1584 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1554d)"
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/JadenGeller/Helium"
  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).

Helium is a native macOS floating browser window built in Swift that stays atop other applications, allowing users to watch media or browse web content while working on other tasks. It features customizable translucency so content remains visible without blocking mouse clicks to windows beneath it—the core innovation is a click-through overlay that lets you interact with your work while keeping reference content permanently visible. Single macOS application with a custom menu framework under Helium/Menu/Framework/ that provides declarative menu DSL (Binding.swift, PrimitiveMenu.swift, HostingMenu.swift). Window management lives in Helium/Window/ (HeliumWindow.swift, HeliumWindowController.swift). App-specific menus (ApplicationMenu.swift, ViewMenu.swift, WindowMenu.swift) use this framework. User settings stored via UserSettings.swift and UserDefaultHelpers.swift.

macOS users who multitask heavily (researchers cross-referencing sources, developers consulting documentation, traders monitoring live feeds) and developers building native macOS applications with WebKit integration who want to understand how to build always-on-top window controllers in Swift.

The project is abandoned—the README explicitly states ':warning: Helium is no longer maintained.' There is no test coverage visible in the file structure, no CI configuration shown, and the codebase appears to be a completed product rather than an actively developed library. It should be treated as reference code or a historical macOS example rather than a dependency.

Critical risk: this is unmaintained with no visible tests, no CI pipeline, and no active development. Swift syntax and macOS APIs have evolved significantly since abandonment, likely causing build failures on modern Xcode versions. The custom menu framework (Menu/Framework/) and window controller patterns may rely on deprecated AppKit APIs. No dependency lock file visible suggests potential version conflicts.

Nothing—project is unmaintained. No active development, no open PRs visible, no recent commits implied by the file structure alone.

Open Helium/Helium.xcodeproj in Xcode and build the Helium scheme. No shell commands required; this is a standard Xcode project with Swift Package Manager dependencies listed in project.xcworkspace/xcshareddata/swiftpm/Package.resolved. xcodebuild -scheme Helium -configuration Release from the Helium/ directory.

Daily commands: Open Helium.xcodeproj in Xcode (Xcode 12+), select the Helium scheme, and press Cmd+R. Or: cd Helium && xcodebuild -scheme Helium build to compile from CLI. The app launches as a standalone macOS application with a floating window.

• Helium/Helium/AppDelegate.swift — Application entry point and lifecycle manager; initializes the window controller and handles OS-level events for the floating browser.
• Helium/Helium/Window/HeliumWindow.swift — Core window definition with translucency, floating behavior, and click-through logic that enables the key UX feature of seeing content behind the window.
• Helium/Helium/Window/WebView/WebViewController.swift — Web content rendering and navigation controller; bridges OS X WebKit with user interactions and toolbar state management.
• Helium/Helium/WindowControllerManager.swift — Singleton managing lifecycle of multiple floating windows; coordinates state synchronization and persistence across app sessions.
• Helium/Helium/Menu/Framework/Menu.swift — Abstract menu DSL foundation; all menu behavior (File, Edit, View, Window, Help) derives from this protocol-based framework.
• Helium/Helium/UserSettings.swift — Settings model binding user preferences (transparency, zoom, size) to persistent storage; required for understanding app configuration flow.
• Helium/Helium/RedirectHandler.swift — URL interception and routing logic; handles navigation events and determines whether to open links in the floating window or system browser.

Add a new toolbar item

1. Create new file in Helium/Helium/Window/Toolbar/Items/ inheriting from NSToolbarItem or using the pattern in DirectionalNavigationButtonsToolbarItem.swift (Helium/Helium/Window/Toolbar/Items/YourToolbarItem.swift)
2. Implement toolbar item initialization and action handler (e.g., button target/action or text field delegate) (Helium/Helium/Window/Toolbar/Items/YourToolbarItem.swift)
3. Register the toolbar item identifier in BrowserToolbar.swift, adding it to the toolbar.allowedItemIdentifiers and toolbar.defaultItems arrays (Helium/Helium/Window/Toolbar/BrowserToolbar.swift)
4. Wire up the action to HeliumWindowController or WebViewController depending on whether it needs window or web content logic (Helium/Helium/Window/HeliumWindowController.swift)

Add a new menu option

1. Create or edit the relevant menu file (FileMenu.swift, EditMenu.swift, ViewMenu.swift, etc.) in Helium/Helium/Menu/ (Helium/Helium/Menu/ViewMenu.swift)
2. Use the Menu DSL primitives (Button, Toggle, Picker, Section) from Helium/Helium/Menu/Framework/Primitives/ to add your menu item (Helium/Helium/Menu/Framework/Primitives/Button.swift)
3. Implement the action handler in the same menu file or delegate to AppDelegate/WebViewController (Helium/Helium/Menu/ViewMenu.swift)
4. If persisting the setting, add a property to UserSettings.swift and store via UserDefaultHelpers.swift (Helium/Helium/UserSettings.swift)

Add a new user setting

1. Add a new @AppStorage or UserDefaults property to UserSettings.swift with a unique key (Helium/Helium/UserSettings.swift)
2. Create getter/setter or computed property if derived logic is needed (Helium/Helium/UserSettings.swift)
3. Use the setting in WebViewController.swift, HeliumWindow.swift, or relevant component by accessing UserSettings singleton (Helium/Helium/Window/WebView/WebViewController.swift)
4. Expose the setting via a menu toggle or button in ViewMenu.swift or a new preferences UI (Helium/Helium/Menu/ViewMenu.swift)

Modify web content behavior or navigation

1. Edit WebViewController.swift to intercept WKNavigationDelegate or WKScriptMessageHandler callbacks (Helium/Helium/Window/WebView/WebViewController.swift)
2. Implement custom logic in webView(:decidePolicyFor:decisionHandler:) or webView(:didFinish:) methods (Helium/Helium/Window/WebView/WebViewController.swift)
3. If URL filtering is needed, modify RedirectHandler.swift to add rules for opening in external browser vs. floating window (Helium/Helium/RedirectHandler.swift)
4. Test behavior in HeliumTests.swift or via manual testing in HeliumWindowController (Helium/HeliumTests/HeliumTests.swift)

• Swift & Cocoa (AppKit) — Native OS X development; required for NSWindow, NSWindowController, menu APIs, and tight OS integration.
• WebKit (WKWebView) — Modern, performant web rendering engine on macOS; supports JavaScript injection and navigation delegation.
• NSUserDefaults — Standard macOS persistent user preferences store; simple key-value for settings like transparency and window size.
• Custom Menu DSL (Protocol-based) — Enables declarative menu composition without boilerplate; allows reusable menu primitives (Button, Toggle, Picker, Section).
• Share Extension (NSExtension) — Integrates with macOS Share menu for seamless URL sharing from other apps into Helium floating windows.

• Always-on-top floating window (via windowLevel)

  • Why: Core UX: never falls behind other windows so user can always see media/content.
  • Consequence: Cannot be hidden by Cmd+Tab or most window managers; requires explicit close or use of translucency + click-through to maintain productivity.

• Click-through translucency mode (mouse events pass to windows behind)

  • Why: Allows simultaneous content viewing and interaction with other applications without window obstruction.
  • Consequence: Cannot interact with Helium content while translucent; user must toggle back to opaque mode to click links.

• Custom Menu DSL over standard NSMenu builders

  • Why: undefined
  • Consequence: undefined

AppKit's NSWindow transparency and click-through masking are tricky—the custom window class likely overrides hitTest(_:) to implement the click-through translucency feature. Swift syntax and AppKit patterns changed significantly post-2019 (when Helium was likely last worked on); modern Xcode may require migration to newer window management APIs. No CocoaPods or SPM manifest visible in top-level, so all dependencies are system frameworks—verify macOS version compatibility. The custom menu framework predates SwiftUI and uses older NSMenu APIs that may not work identically on Big Sur+.

• Hit Testing & Click-Through Windows — Core to Helium's UX—the translucent mode that lets clicks pass through to windows beneath requires custom NSView hit-testing logic, a non-obvious AppKit pattern essential for this app's key feature.
• Window Level & Z-Order Management — Keeping Helium atop all other windows requires NSWindow.level manipulation; understanding macOS window layering is critical for building always-on-top applications.
• Declarative UI via Protocol-Oriented Programming — Helium's custom menu framework (Menu/Framework/) predates SwiftUI and uses Swift protocols (PrimitiveMenu) to build a declarative DSL—a clever pattern worth studying for understanding how to layer abstractions over imperative frameworks.
• AppKit Window Controllers & Lifecycle — HeliumWindowController.swift manages the window lifecycle without modern SwiftUI; understanding NSWindowController's delegate patterns and responder chain is essential for old-style macOS apps.
• UserDefaults Persistence & Serialization — UserSettings.swift encodes app state (window size, opacity, position) to UserDefaults for resume-on-launch; this pattern is fundamental to stateful macOS utilities.
• Application Menus & Menu Items (AppKit NSMenu) — The entire Menu/ directory is custom menu management built atop AppKit's imperative NSMenu—understanding how macOS menu bars work is prerequisite for this codebase.
• WebKit Integration & URL Handling — RedirectHandler.swift suggests custom URL interception and content loading; integrating WebKit into a native app window is not trivial and requires understanding WKWebView delegation.

• soulverteam/Helium-iOS — Potential iOS variant or spin-off exploring similar always-on-top/floating window patterns on a different Apple platform
• jordansinger/Xcode-Editor — Similar native macOS application using AppKit for UI, demonstrating alternative patterns for building sophisticated floating/palettized interfaces
• slackhq/PastePal-Clipboard-Manager — Another macOS utility using similar always-on-top window + menu bar patterns for productivity features
• apple/swift-corelibs-foundation — Upstream Swift and Foundation—useful for understanding UserDefaults behavior and modern AppKit best practices
• WebKit/WebKit — Likely embedded in Helium for content rendering; source reference for the browser engine powering the floating window

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.

Add unit tests for Menu Framework components

The Menu/Framework directory contains custom SwiftUI menu primitives (Binding.swift, PrimitiveMenu.swift, HostingMenu.swift, and Derived components) but HeliumTests/HeliumTests.swift is empty. These custom menu abstractions are core to the app's UI and lack test coverage. Testing menu bindings, picker/toggle interactions, and menu composition would catch regressions and make maintenance easier for future contributors.

• [ ] Create test cases in HeliumTests/HeliumTests.swift for Menu/Framework/Binding.swift data flow
• [ ] Add tests for Menu/Framework/Derived/Picker.swift and Toggle.swift state management
• [ ] Test Menu/Framework/Primitives/Button.swift, MenuButton.swift, and Section.swift rendering and interaction
• [ ] Verify HostingMenu.swift correctly bridges SwiftUI menus to NSMenu

Add GitHub Actions workflow for macOS app builds and signing

The repo has Xcode project files (Helium.xcodeproj with schemes and entitlements) and a share extension, but no CI/CD pipeline to validate builds. A GitHub Actions workflow would catch build failures early, validate Swift compilation across macOS SDK versions, and document the build/signing process for contributors. The presence of HeliumShareExtension.entitlements indicates signing requirements that should be automated.

• [ ] Create .github/workflows/build.yml to run 'xcodebuild build' for Helium scheme on macOS runner
• [ ] Add validation for HeliumShareExtension.xcscheme builds
• [ ] Include Swift linting step if applicable (or document why it's skipped)
• [ ] Test against multiple macOS deployment targets specified in Info.plist

Refactor WebViewController into focused modules for browser state and UI updates

Window/WebView/WebViewController.swift likely contains mixed concerns: WKWebView delegate logic, toolbar item updates, window state management, and URL/search handling. The repo has separate toolbar items (SearchFieldToolbarItem.swift, DirectionalNavigationButtonsToolbarItem.swift) suggesting these should coordinate with WebViewController, but the current monolithic structure makes this hard. Splitting into WebViewState and WebViewUIController modules would improve testability and make the architecture clearer.

• [ ] Extract WebView delegate implementations (WKNavigationDelegate, WKUIDelegate) into a separate WebViewDelegate.swift
• [ ] Create WebViewState.swift to manage navigation history, URL, and loading state separate from UI updates
• [ ] Move toolbar synchronization logic into a ToolbarCoordinator.swift that observes WebViewState
• [ ] Update Window/Toolbar/Items/* to bind to WebViewState instead of directly accessing WebViewController

• Add unit tests for UserSettings.swift serialization—currently no test coverage visible; write tests for encoding/decoding settings to/from UserDefaults to prevent regression when updating the settings schema.
• Document the custom menu framework DSL—create a guide explaining how to use Binding.swift, Picker.swift, Toggle.swift, and the Primitives/ components, with code examples, since the framework is undocumented custom code that new contributors will struggle to understand.
• Audit and fix AppKit deprecations for modern macOS versions—identify deprecated NSWindow/NSView methods called in HeliumWindow.swift and HeliumWindowController.swift and migrate to modern alternatives (likely NSWindowSceneDelegate patterns if targeting newer macOS).

Helium presents a LOW-TO-MEDIUM security posture with several concerning factors. The most critical issue is that the project is explicitly unmaintained, meaning no security patches will be released for discovered vulnerabilities. The application handles web content rendering without visible security controls (CSP, sandboxing specifics). User data is stored in unencrypted UserDefaults, and custom URL handling introduces redirect risks. Additionally, the share extension's entitlements and Swift Package dependencies lack visible security review. The codebase appears to lack comprehensive security testing. For production use or further development, significant security hardening is required, including implementing CSP, switching sensitive data to Key

• High · Unmaintained Project with No Security Updates — README.md, project status. The README explicitly states 'Helium is no longer maintained.' This means the project will not receive security patches, dependency updates, or bug fixes. Any vulnerabilities discovered will remain unaddressed indefinitely. Fix: Consider forking the project and maintaining it independently, or switch to an actively maintained alternative. If continuing use, implement additional security controls at the deployment level.
• High · WebView Integration Without Visible Security Controls — Helium/Helium/Window/WebView/WebViewController.swift. The application uses WebViewController to render web content in a floating browser window. Without visible implementation of Content Security Policy (CSP), X-Frame-Options, or input sanitization in the codebase review, there is a potential XSS vulnerability risk when loading untrusted web content. Fix: Implement and enforce strict Content Security Policy headers. Validate and sanitize all user inputs. Disable JavaScript execution for untrusted content if not required. Review WebKit security settings and disable dangerous features.
• Medium · Potential URL Redirect/Handler Vulnerability — Helium/Helium/RedirectHandler.swift. The RedirectHandler.swift file suggests custom URL handling logic. Without visible input validation, this could be exploited for open redirect vulnerabilities or protocol handler attacks (e.g., javascript://, file://). Fix: Implement strict whitelist validation for all URL schemes. Use URLComponents to parse and validate URLs. Prevent execution of dangerous schemes (javascript:, data:, file:). Log all redirect attempts.
• Medium · UserDefaults Data Storage Without Encryption — Helium/Helium/UserSettings.swift, Helium/Helium/UserDefaultHelpers.swift. UserDefaults is used for storing user settings and preferences (UserSettings.swift, UserDefaultHelpers.swift). UserDefaults stores data in plain text XML/plist format on disk and is not encrypted, making sensitive user data vulnerable to local access attacks. Fix: For sensitive data, use Keychain instead of UserDefaults. If UserDefaults must be used, encrypt sensitive values before storage. Avoid storing credentials, tokens, or PII in UserDefaults.
• Medium · Share Extension Entitlements Not Reviewed — Helium/HeliumShareExtension/HeliumShareExtension.entitlements. The HeliumShareExtension has entitlements configuration (HeliumShareExtension.entitlements) that could grant excessive permissions. Share extensions run in a separate sandbox context and need careful entitlements management. Fix: Review entitlements and apply principle of least privilege. Only grant necessary entitlements. Document why each entitlement is required. Regularly audit extension permissions.
• Low · Missing Package.resolved Dependency Verification — Helium/Helium.xcodeproj/project.xcworkspace/xcshareddata/swiftpm/Package.resolved. The project uses Swift Package Manager (Package.resolved exists), but without access to the actual dependencies list, there could be unvetted or outdated package dependencies with known vulnerabilities. Fix: Regularly audit Swift packages using 'swift package dependencies' command. Monitor for security advisories. Keep packages updated. Use dependency pinning for reproducible builds.
• Low · Test Coverage Not Evident — Helium/HeliumTests/HeliumTests.swift. HeliumTests directory exists but no comprehensive security-focused tests are visible. Browser applications handling web content should have extensive security testing. Fix: Implement comprehensive security tests including XSS prevention, CSRF protection, input validation, and URL handling. Add tests for malicious payload handling.

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.