sparkbun 0.1.0

package/src/native/shared/accelerator_parser.h

@@ -0,0 +1,72 @@
+// accelerator_parser.h - Cross-platform Electron-style accelerator string parser
+// Parses strings like "CommandOrControl+Shift+T" into modifier flags and a key.
+// Header-only to match the pattern of json_menu_parser.h.
+
+#ifndef ELECTROBUN_ACCELERATOR_PARSER_H
+#define ELECTROBUN_ACCELERATOR_PARSER_H
+
+#include <string>
+#include <vector>
+#include <algorithm>
+
+namespace electrobun {
+
+struct AcceleratorParts {
+    std::string key;                // The key, lowercased (e.g. "t", "f1", "space")
+    bool commandOrControl = false;  // "commandorcontrol" or "cmdorctrl"
+    bool command = false;           // "command" or "cmd"
+    bool control = false;           // "control" or "ctrl"
+    bool alt = false;               // "alt" or "option"
+    bool shift = false;             // "shift"
+    bool super = false;             // "super", "meta", or "win"
+
+    // True when the accelerator was a bare key with no modifier prefix.
+    bool isBareKey = false;
+};
+
+// Parse an Electron-style accelerator string into its component parts.
+// Modifier names are case-insensitive. The key is always lowercased.
+inline AcceleratorParts parseAccelerator(const std::string& accelerator) {
+    AcceleratorParts result;
+    std::vector<std::string> parts;
+
+    // Split by '+'
+    size_t start = 0, end;
+    while ((end = accelerator.find('+', start)) != std::string::npos) {
+        parts.push_back(accelerator.substr(start, end - start));
+        start = end + 1;
+    }
+    parts.push_back(accelerator.substr(start));
+
+    // Last component is the key
+    result.key = parts.back();
+    std::transform(result.key.begin(), result.key.end(), result.key.begin(), ::tolower);
+    parts.pop_back();
+
+    result.isBareKey = parts.empty();
+
+    for (const auto& part : parts) {
+        std::string lower = part;
+        std::transform(lower.begin(), lower.end(), lower.begin(), ::tolower);
+
+        if (lower == "commandorcontrol" || lower == "cmdorctrl") {
+            result.commandOrControl = true;
+        } else if (lower == "command" || lower == "cmd") {
+            result.command = true;
+        } else if (lower == "control" || lower == "ctrl") {
+            result.control = true;
+        } else if (lower == "alt" || lower == "option") {
+            result.alt = true;
+        } else if (lower == "shift") {
+            result.shift = true;
+        } else if (lower == "super" || lower == "meta" || lower == "win") {
+            result.super = true;
+        }
+    }
+
+    return result;
+}
+
+} // namespace electrobun
+
+#endif // ELECTROBUN_ACCELERATOR_PARSER_H

package/src/native/shared/app_paths.h

@@ -0,0 +1,110 @@
+#ifndef ELECTROBUN_APP_PATHS_H
+#define ELECTROBUN_APP_PATHS_H
+
+#include <string>
+
+namespace electrobun {
+
+/**
+ * Build the app data path using identifier/channel structure.
+ * This ensures consistent path structure across all platforms and matches
+ * the CLI and updater conventions.
+ *
+ * @param basePath The base application support/data path (e.g., ~/Library/Application Support)
+ * @param identifier The app identifier (e.g., "sh.blackboard.electrobun-kitchen")
+ * @param channel The release channel (e.g., "dev", "canary", "stable")
+ * @param suffix Optional suffix to append (e.g., "CEF", "WebView2")
+ * @param pathSeparator The path separator to use ('/' for Unix, '\\' for Windows)
+ * @return The full path: basePath/identifier/channel/suffix
+ */
+inline std::string buildAppDataPath(
+    const std::string& basePath,
+    const std::string& identifier,
+    const std::string& channel,
+    const std::string& suffix = "",
+    char pathSeparator = '/'
+) {
+    std::string appId = !identifier.empty() ? identifier : "Electrobun";
+    std::string channelPath = !channel.empty() ? channel : "default";
+
+    std::string result = basePath;
+    result += pathSeparator;
+    result += appId;
+    result += pathSeparator;
+    result += channelPath;
+
+    if (!suffix.empty()) {
+        result += pathSeparator;
+        result += suffix;
+    }
+
+    return result;
+}
+
+/**
+ * Build a partition-specific path under the app data directory.
+ *
+ * @param basePath The base application support/data path
+ * @param identifier The app identifier
+ * @param channel The release channel
+ * @param renderer The renderer type (e.g., "CEF", "WebView2", "WebKit")
+ * @param partitionName The partition name
+ * @param pathSeparator The path separator to use
+ * @return The full path: basePath/identifier/channel/renderer/Partitions/partitionName
+ */
+inline std::string buildPartitionPath(
+    const std::string& basePath,
+    const std::string& identifier,
+    const std::string& channel,
+    const std::string& renderer,
+    const std::string& partitionName,
+    char pathSeparator = '/'
+) {
+    std::string base = buildAppDataPath(basePath, identifier, channel, renderer, pathSeparator);
+    base += pathSeparator;
+    base += "Partitions";
+    base += pathSeparator;
+    base += partitionName;
+    return base;
+}
+
+/**
+ * Build a CEF partition-specific path under the renderer root.
+ *
+ * Partitions live in a `partitions/` subdirectory of the renderer cache root
+ * rather than directly under it. The renderer root itself is CefSettings.cache_path,
+ * which Chromium populates with auto-created profile directories such as
+ * `Default`, `System Profile`, etc. On case-insensitive filesystems (Windows
+ * NTFS, macOS APFS in default config) a partition literally named `default`
+ * would collide with that auto-created `Default` folder; CEF then refuses to
+ * bind a CefRequestContext to the colliding path and CreateBrowserSync
+ * silently returns null. Nesting under `partitions/` keeps user partitions
+ * cleanly separated from Chromium's own profile state.
+ *
+ * @param basePath The base application support/data path
+ * @param identifier The app identifier
+ * @param channel The release channel
+ * @param renderer The renderer type (typically "CEF")
+ * @param partitionName The partition name
+ * @param pathSeparator The path separator to use
+ * @return The full path: basePath/identifier/channel/renderer/partitions/partitionName
+ */
+inline std::string buildCEFPartitionPath(
+    const std::string& basePath,
+    const std::string& identifier,
+    const std::string& channel,
+    const std::string& renderer,
+    const std::string& partitionName,
+    char pathSeparator = '/'
+) {
+    std::string base = buildAppDataPath(basePath, identifier, channel, renderer, pathSeparator);
+    base += pathSeparator;
+    base += "partitions";
+    base += pathSeparator;
+    base += partitionName;
+    return base;
+}
+
+} // namespace electrobun
+
+#endif // ELECTROBUN_APP_PATHS_H

package/src/native/shared/asar.h

@@ -0,0 +1,35 @@
+// asar.h - Cross-platform ASAR archive C FFI declarations
+// Used for reading files from ASAR archives across Windows, macOS, and Linux
+//
+// This is a header-only declaration file. The actual implementation is provided by:
+// - libasar library (macOS, Linux)
+// - Built-in AsarArchive class (Windows)
+
+#ifndef ELECTROBUN_ASAR_H
+#define ELECTROBUN_ASAR_H
+
+#include <cstdint>
+#include <cstddef>
+#include <mutex>
+
+// C FFI declarations for ASAR archive operations
+// These match the libasar library API
+extern "C" {
+    typedef struct AsarArchive AsarArchive;
+
+    AsarArchive* asar_open(const char* path);
+    void asar_close(AsarArchive* archive);
+    const uint8_t* asar_read_file(AsarArchive* archive, const char* path, size_t* size_out);
+    void asar_free_buffer(const uint8_t* buffer, size_t size);
+}
+
+namespace electrobun {
+
+// Global ASAR archive handle (lazy-loaded) with thread-safe initialization
+// Each platform should define these in their nativeWrapper implementation
+// as: static AsarArchive* g_asarArchive = nullptr;
+//     static std::once_flag g_asarArchiveInitFlag;
+
+} // namespace electrobun
+
+#endif // ELECTROBUN_ASAR_H

package/src/native/shared/cache_migration.h

@@ -0,0 +1,244 @@
+// cache_migration.h - One-shot CEF cache folder wipe on Electrobun upgrades.
+//
+// When Electrobun ships a release whose CEF cache folder layout/contents are
+// incompatible with prior releases (e.g. a CEF major bump that surfaces
+// "Profile error" dialogs, or an Electrobun-side change to partition layout),
+// the simplest reliable recovery is to wipe the cache folder. End users will
+// be logged out of sites they were logged into via the app, but the app
+// starts cleanly with no dialogs.
+//
+// Bump CEF_CACHE_FORMAT_VERSION below MANUALLY when (and only when) such a
+// breaking change ships. Independent of CEF_VERSION — bumping CEF does not
+// always require a wipe.
+//
+// Behavior:
+//   1. Reads <cacheFolder>/.electrobun_cef_cache_version on startup.
+//   2. If the sentinel is missing OR its value != CEF_CACHE_FORMAT_VERSION,
+//      deletes everything inside cacheFolder (preserving the folder itself)
+//      and writes a fresh sentinel.
+//   3. If the folder doesn't exist yet (fresh install), creates it and
+//      writes the sentinel — so first real launch isn't mistaken for an
+//      "old layout" that needs wiping.
+//   4. If the folder exists but is effectively empty (no contents, or only
+//      our sentinel), refreshes the sentinel without wiping anything.
+//
+// Safety guards (any failure → no-op, never wipe):
+//   - empty / null / relative paths
+//   - paths whose final component isn't a known Electrobun cache name
+//   - paths shallower than 3 components below the filesystem root
+//   - any std::filesystem exception
+//
+// Callers must invoke this AFTER computing the cache path and BEFORE
+// CefInitialize is called for that path. Multi-process locking is NOT
+// implemented: Electrobun's app process starts before any windows open,
+// so concurrent first-launch races aren't a concern in practice.
+
+#ifndef ELECTROBUN_CACHE_MIGRATION_H
+#define ELECTROBUN_CACHE_MIGRATION_H
+
+#include <cstdint>
+#include <cstdio>
+#include <exception>
+#include <filesystem>
+#include <fstream>
+#include <string>
+#include <system_error>
+
+namespace electrobun {
+
+// MANUAL bump only. Increment when a release requires that end users'
+// existing CEF cache folders be wiped on first launch after upgrade.
+// Reasons that justify a bump:
+//   - CEF major-version jump that's known to surface profile-error dialogs
+//   - Electrobun-side change to cache folder layout (e.g. partition path)
+//   - Any other situation where stale state would degrade the user experience
+//     in a way Chromium's own forward-migration can't handle.
+// Bumping invalidates cookies/logins/site data for all users on first launch.
+//   v2: partitions moved from <root>/<name> to <root>/partitions/<name> to
+//       avoid case-insensitive collisions with Chromium's auto-created
+//       <root>/Default profile folder.
+constexpr uint32_t CEF_CACHE_FORMAT_VERSION = 2;
+
+inline const char* cacheSentinelFilename() {
+    return ".electrobun_cef_cache_version";
+}
+
+inline uint32_t readCacheSentinel(const std::filesystem::path& sentinelPath) {
+    std::ifstream in(sentinelPath);
+    if (!in) return 0;
+    uint32_t v = 0;
+    in >> v;
+    return in ? v : 0;
+}
+
+inline void writeCacheSentinel(const std::filesystem::path& sentinelPath,
+                               uint32_t version) {
+    std::filesystem::path tmpPath = sentinelPath;
+    tmpPath += ".tmp";
+    {
+        std::ofstream out(tmpPath, std::ios::trunc);
+        if (!out) {
+            fprintf(stderr,
+                    "[cache_migration] warning: cannot open sentinel temp file: %s\n",
+                    tmpPath.string().c_str());
+            return;
+        }
+        out << version << "\n";
+        if (!out) {
+            fprintf(stderr,
+                    "[cache_migration] warning: failed writing sentinel temp file\n");
+            return;
+        }
+    }
+    std::error_code ec;
+    std::filesystem::rename(tmpPath, sentinelPath, ec);
+    if (ec) {
+        fprintf(stderr,
+                "[cache_migration] warning: failed to commit sentinel: %s\n",
+                ec.message().c_str());
+        std::error_code rmEc;
+        std::filesystem::remove(tmpPath, rmEc);
+    }
+}
+
+// Refuses paths that look unsafe to wipe. Returns true only when the path
+// is absolute, ends in a recognized Electrobun cache folder name, and is
+// at least 3 components deep below the filesystem root.
+inline bool isCachePathSafeToWipe(const std::filesystem::path& cachePath) {
+    if (cachePath.empty()) return false;
+    if (!cachePath.is_absolute()) return false;
+
+    const std::string leaf = cachePath.filename().string();
+    if (leaf != "CEF" && leaf != "cef_cache") return false;
+
+    size_t depth = 0;
+    for (const auto& part : cachePath.relative_path()) {
+        (void)part;
+        ++depth;
+    }
+    // Require at least: <user-dir-component>/<identifier>/<channel>/<leaf>
+    // i.e. four below the root. Three is the floor; below that we refuse.
+    if (depth < 3) return false;
+
+    return true;
+}
+
+inline void migrateCacheFolderIfNeeded(const std::string& cacheFolderPath) {
+    try {
+        if (cacheFolderPath.empty()) {
+            fprintf(stderr,
+                    "[cache_migration] skipped: empty cache path\n");
+            return;
+        }
+
+        const std::filesystem::path cachePath(cacheFolderPath);
+
+        if (!isCachePathSafeToWipe(cachePath)) {
+            fprintf(stderr,
+                    "[cache_migration] skipped: path failed safety check: %s\n",
+                    cacheFolderPath.c_str());
+            return;
+        }
+
+        const std::filesystem::path sentinelPath =
+            cachePath / cacheSentinelFilename();
+
+        std::error_code ec;
+        const bool cacheExists = std::filesystem::exists(cachePath, ec);
+
+        if (!cacheExists) {
+            // Fresh install: create the folder and stamp the current sentinel
+            // so the next launch (when CEF has populated it) doesn't see a
+            // populated folder + missing sentinel and mistake it for an old
+            // layout that needs wiping.
+            std::error_code mkEc;
+            std::filesystem::create_directories(cachePath, mkEc);
+            if (mkEc) {
+                fprintf(stderr,
+                        "[cache_migration] skipped: cannot create cache folder %s (%s)\n",
+                        cacheFolderPath.c_str(), mkEc.message().c_str());
+                return;
+            }
+            writeCacheSentinel(sentinelPath, CEF_CACHE_FORMAT_VERSION);
+            return;
+        }
+
+        if (!std::filesystem::is_directory(cachePath, ec)) {
+            fprintf(stderr,
+                    "[cache_migration] skipped: path exists but is not a directory: %s\n",
+                    cacheFolderPath.c_str());
+            return;
+        }
+
+        // Determine if folder is effectively empty (only sentinel or nothing).
+        bool effectivelyEmpty = true;
+        {
+            std::error_code itEc;
+            std::filesystem::directory_iterator it(cachePath, itEc);
+            if (itEc) {
+                fprintf(stderr,
+                        "[cache_migration] skipped: cannot enumerate cache folder %s (%s)\n",
+                        cacheFolderPath.c_str(), itEc.message().c_str());
+                return;
+            }
+            for (const auto& entry : it) {
+                if (entry.path().filename() == sentinelPath.filename()) continue;
+                effectivelyEmpty = false;
+                break;
+            }
+        }
+
+        if (effectivelyEmpty) {
+            writeCacheSentinel(sentinelPath, CEF_CACHE_FORMAT_VERSION);
+            return;
+        }
+
+        const uint32_t existingVersion =
+            std::filesystem::exists(sentinelPath, ec)
+                ? readCacheSentinel(sentinelPath)
+                : 0;
+
+        if (existingVersion == CEF_CACHE_FORMAT_VERSION) {
+            return;
+        }
+
+        fprintf(stderr,
+                "[cache_migration] wiping CEF cache folder (format %u -> %u): %s\n",
+                existingVersion, CEF_CACHE_FORMAT_VERSION,
+                cacheFolderPath.c_str());
+
+        // Wipe contents but preserve the folder itself. Per-entry failures
+        // are warned and skipped — a partial wipe still beats refusing to
+        // start the app cleanly.
+        std::error_code itEc;
+        std::filesystem::directory_iterator it(cachePath, itEc);
+        if (itEc) {
+            fprintf(stderr,
+                    "[cache_migration] warning: cannot enumerate cache folder for wipe %s (%s)\n",
+                    cacheFolderPath.c_str(), itEc.message().c_str());
+            return;
+        }
+        for (const auto& entry : it) {
+            std::error_code rmEc;
+            std::filesystem::remove_all(entry.path(), rmEc);
+            if (rmEc) {
+                fprintf(stderr,
+                        "[cache_migration] warning: failed to remove %s (%s)\n",
+                        entry.path().string().c_str(), rmEc.message().c_str());
+            }
+        }
+
+        writeCacheSentinel(sentinelPath, CEF_CACHE_FORMAT_VERSION);
+    } catch (const std::exception& e) {
+        fprintf(stderr,
+                "[cache_migration] aborting due to filesystem error: %s\n",
+                e.what());
+    } catch (...) {
+        fprintf(stderr,
+                "[cache_migration] aborting due to unknown error\n");
+    }
+}
+
+}  // namespace electrobun
+
+#endif  // ELECTROBUN_CACHE_MIGRATION_H

package/src/native/shared/callbacks.h

@@ -0,0 +1,57 @@
+// callbacks.h - Cross-platform callback type definitions
+// Used for bridging between native code and Zig/Bun FFI across Windows, macOS, and Linux
+//
+// This is a header-only implementation to avoid build complexity.
+
+#ifndef ELECTROBUN_CALLBACKS_H
+#define ELECTROBUN_CALLBACKS_H
+
+#include <cstdint>
+
+namespace electrobun {
+
+// Webview navigation and event callbacks
+// NOTE: Bun's FFIType.true doesn't play well with Objective-C's YES/NO char booleans
+// so when sending booleans from JSCallbacks we use uint32_t
+typedef uint32_t (*DecideNavigationCallback)(uint32_t webviewId, const char* url);
+typedef void (*WebviewEventHandler)(uint32_t webviewId, const char* type, const char* url);
+typedef void (*HandlePostMessage)(uint32_t webviewId, const char* message);
+typedef const char* (*HandlePostMessageWithReply)(uint32_t webviewId, const char* message);
+typedef void (*AsyncJavascriptCompletionHandler)(const char* messageId, uint32_t webviewId, uint32_t hostWebviewId, const char* responseJSON);
+
+// Window chrome style enum, shared across platforms for titleBarStyle handling
+enum class ChromeStyle : uint32_t { Default, Hidden, HiddenInset };
+
+// Window event callbacks
+typedef void (*WindowCloseHandler)(uint32_t windowId);
+typedef void (*WindowMoveHandler)(uint32_t windowId, double x, double y);
+typedef void (*WindowResizeHandler)(uint32_t windowId, double x, double y, double width, double height);
+typedef void (*WindowFocusHandler)(uint32_t windowId);
+typedef void (*WindowBlurHandler)(uint32_t windowId);
+typedef void (*WindowKeyHandler)(uint32_t windowId, uint32_t keyCode, uint32_t modifiers, uint32_t isDown, uint32_t isRepeat);
+
+// Tray and menu callbacks
+typedef void (*StatusItemHandler)(uint32_t trayId, const char* action);
+typedef void (*MenuHandler)(const char* menuItemId);
+
+// Snapshot callback
+typedef void (*SnapshotCallback)(uint32_t hostId, uint32_t webviewId, const char* dataUrl);
+
+// URL open handler for deep linking
+typedef void (*URLOpenHandler)(const char* url);
+
+// App reopen handler - called when the user re-opens an already running app
+// (for example via Finder, Launchpad, or `open -a` on macOS)
+typedef void (*AppReopenHandler)();
+
+// Quit request handler - called by native code when quit is requested externally
+// (e.g., dock icon quit, system shutdown, console close)
+typedef void (*QuitRequestedHandler)();
+
+// JS Utils callbacks (DEPRECATED: Now using map-based approach instead)
+typedef const char* (*GetMimeType)(const char* filePath);
+typedef const char* (*GetHTMLForWebviewSync)(uint32_t webviewId);
+
+} // namespace electrobun
+
+#endif // ELECTROBUN_CALLBACKS_H