cleanup

Author: ItsMeSamey

src/embedded_index.zig

@@ -26,7 +26,7 @@ pub fn setEnvironMap(environ_map: *std.process.Environ.Map) void {
     process_environ_map = environ_map;
 }
 
-// Split index template.
+/// Splits the built HTML shell around the bootstrap placeholder inserted at build time.
 fn splitIndexTemplate(html: []const u8) ?IndexTemplate {
     const marker_index = std.mem.indexOf(u8, html, BOOTSTRAP_PLACEHOLDER) orelse return null;
     return .{
@@ -35,13 +35,7 @@ fn splitIndexTemplate(html: []const u8) ?IndexTemplate {
     };
 }
 
-// Path exists.
-fn pathExists(path: []const u8) bool {
-    std.Io.Dir.accessAbsolute(process_io, path, .{}) catch return false;
-    return true;
-}
-
-// Returns get env var owned compat.
+/// Reads an environment variable into owned memory across libc and no-libc targets.
 fn getEnvVarOwnedCompat(allocator: std.mem.Allocator, key: []const u8) ![]u8 {
     if (process_environ_map) |environ_map| {
         if (environ_map.get(key)) |value| {
@@ -64,23 +58,15 @@ fn getEnvVarOwnedCompat(allocator: std.mem.Allocator, key: []const u8) ![]u8 {
     return error.EnvironmentVariableNotFound;
 }
 
-// Returns get home dir.
-fn getHomeDir(allocator: std.mem.Allocator) ![]u8 {
-    if (builtin.os.tag == .windows) {
-        return getEnvVarOwnedCompat(allocator, "USERPROFILE");
-    }
-    return getEnvVarOwnedCompat(allocator, "HOME");
-}
-
-// Returns get app local data dir.
+/// Resolves the per-user application data directory used for bootstrap-state and live HTML.
 fn getAppLocalDataDir(allocator: std.mem.Allocator) ![]u8 {
     if (builtin.os.tag == .windows) {
         const appdata = try getEnvVarOwnedCompat(allocator, "APPDATA");
         defer allocator.free(appdata);
         return std.fs.path.join(allocator, &.{ appdata, APP_ID });
     }
 
-    const home = try getHomeDir(allocator);
+    const home = try getEnvVarOwnedCompat(allocator, "HOME");
     defer allocator.free(home);
 
     if (builtin.os.tag == .macos) {
@@ -90,21 +76,14 @@ fn getAppLocalDataDir(allocator: std.mem.Allocator) ![]u8 {
     return std.fs.path.join(allocator, &.{ home, ".local", "share", APP_ID });
 }
 
-// Builds the bootstrap-state file path in the per-user application data directory.
-fn bootstrapStatePath(allocator: std.mem.Allocator) ![]u8 {
-    const app_dir = try getAppLocalDataDir(allocator);
-    defer allocator.free(app_dir);
-    return std.fs.path.join(allocator, &.{ app_dir, BOOTSTRAP_STATE_FILE });
-}
-
 /// Returns the path to the generated live `index.html` that webui serves at runtime.
 pub fn liveIndexPath(allocator: std.mem.Allocator) ![]u8 {
     const app_dir = try getAppLocalDataDir(allocator);
     defer allocator.free(app_dir);
     return std.fs.path.join(allocator, &.{ app_dir, LIVE_INDEX_FILE });
 }
 
-// Writes write text file atomic.
+/// Writes a file by replacing it atomically so readers never observe a partial HTML snapshot.
 fn writeTextFileAtomic(allocator: std.mem.Allocator, path: []const u8, contents: []const u8) !void {
     if (std.fs.path.dirname(path)) |parent| {
         try std.Io.Dir.cwd().createDirPath(process_io, parent);
@@ -121,16 +100,18 @@ fn writeTextFileAtomic(allocator: std.mem.Allocator, path: []const u8, contents:
     try std.Io.Dir.renameAbsolute(temp_path, path, process_io);
 }
 
-// Loads the saved bootstrap-state JSON or falls back to the built-in default payload.
+/// Loads the persisted bootstrap-state JSON, normalizing empty/missing files to the default payload.
 fn readBootstrapStateJsonOrDefault(allocator: std.mem.Allocator) ![]u8 {
-    const state_path = bootstrapStatePath(allocator) catch {
-        return allocator.dupe(u8, DEFAULT_BOOTSTRAP_STATE_JSON);
-    };
+    const state_path = blk: {
+        const app_dir = getAppLocalDataDir(allocator) catch break :blk null;
+        defer allocator.free(app_dir);
+        break :blk try std.fs.path.join(allocator, &.{ app_dir, BOOTSTRAP_STATE_FILE });
+    } orelse return allocator.dupe(u8, DEFAULT_BOOTSTRAP_STATE_JSON);
     defer allocator.free(state_path);
 
-    if (!pathExists(state_path)) {
+    std.Io.Dir.accessAbsolute(process_io, state_path, .{}) catch {
         return allocator.dupe(u8, DEFAULT_BOOTSTRAP_STATE_JSON);
-    }
+    };
 
     const raw = std.Io.Dir.cwd().readFileAlloc(process_io, state_path, allocator, .limited(8 * 1024 * 1024)) catch {
         return allocator.dupe(u8, DEFAULT_BOOTSTRAP_STATE_JSON);
@@ -154,29 +135,24 @@ fn readBootstrapStateJsonOrDefault(allocator: std.mem.Allocator) ![]u8 {
     return normalized;
 }
 
-// Serializes the in-memory default bootstrap-state payload.
-fn fallbackBootstrapStateJson(allocator: std.mem.Allocator) ![]u8 {
-    return allocator.dupe(u8, DEFAULT_BOOTSTRAP_STATE_JSON);
-}
-
-// Normalizes bootstrap JSON before it is embedded into the live HTML shell.
+/// Canonicalizes bootstrap JSON so the generated live HTML always embeds valid compact JSON.
 fn canonicalizeBootstrapJson(allocator: std.mem.Allocator, bootstrap_json: []const u8) ![]u8 {
     var parsed = std.json.parseFromSlice(std.json.Value, allocator, bootstrap_json, .{}) catch {
-        return fallbackBootstrapStateJson(allocator);
+        return allocator.dupe(u8, DEFAULT_BOOTSTRAP_STATE_JSON);
     };
     defer parsed.deinit();
 
     switch (parsed.value) {
         .object => {},
-        else => return fallbackBootstrapStateJson(allocator),
+        else => return allocator.dupe(u8, DEFAULT_BOOTSTRAP_STATE_JSON),
     }
 
     return std.fmt.allocPrint(allocator, "{f}", .{
         std.json.fmt(parsed.value, .{}),
     });
 }
 
-// Makes sure the generated HTML includes the webui bridge bootstrap script.
+/// Injects the webui bridge script tag when the built frontend omitted it.
 fn ensureModuleWebUiScript(allocator: std.mem.Allocator, html: []const u8) ![]u8 {
     const script_tag = "<script src=\"/webui_bridge.js\"></script>";
 

src/main.zig

@@ -11,15 +11,15 @@ const LaunchRequest = struct {
     surfaces: [3]?webui.LaunchSurface = .{ null, null, null },
     len: usize = 0,
 
-    // Append.
+    /// Appends a launch surface once while preserving the user-specified order.
     fn append(self: *LaunchRequest, surface: webui.LaunchSurface) void {
         if (self.contains(surface)) return;
         if (self.len >= self.surfaces.len) return;
         self.surfaces[self.len] = surface;
         self.len += 1;
     }
 
-    // Contains.
+    /// Returns whether the request already includes the given launch surface.
     fn contains(self: *const LaunchRequest, surface: webui.LaunchSurface) bool {
         for (self.surfaces[0..self.len]) |entry| {
             if (entry == surface) return true;
@@ -49,7 +49,7 @@ pub fn main(init: std.process.Init) !void {
     try runModeService(allocator, init.io, live_index_path, window_style, launch_request);
 }
 
-// Parses parse launch request.
+/// Parses CLI launch flags into an ordered surface preference list for webui.
 fn parseLaunchRequest(args: std.process.Args, allocator: std.mem.Allocator) !LaunchRequest {
     var request: LaunchRequest = .{};
     var arg_it = try std.process.Args.Iterator.initAllocator(args, allocator);
@@ -88,7 +88,7 @@ fn parseLaunchRequest(args: std.process.Args, allocator: std.mem.Allocator) !Lau
     return request;
 }
 
-// Runs run mode service.
+/// Creates the webui service with the requested launch policy and keeps it alive until shutdown.
 fn runModeService(
     allocator: std.mem.Allocator,
     io: std.Io,
@@ -165,7 +165,7 @@ fn runModeService(
     service.shutdown();
 }
 
-// Ensure native webview available.
+/// Rejects explicit native-only launches when the runtime can only fall back to another surface.
 fn ensureNativeWebviewAvailable(service: *webui.Service, allocator: std.mem.Allocator) !void {
     const capabilities = service.probeCapabilities();
     if (capabilities.surface_if_shown != .native_webview or capabilities.fallback_expected) {
@@ -183,7 +183,7 @@ fn ensureNativeWebviewAvailable(service: *webui.Service, allocator: std.mem.Allo
     try logMissingNativeRequirements(service, allocator);
 }
 
-// Log missing native requirements.
+/// Logs missing native runtime requirements and fails if any required dependency is unavailable.
 fn logMissingNativeRequirements(service: *webui.Service, allocator: std.mem.Allocator) !void {
     const requirements = try service.listRuntimeRequirements(allocator);
     defer allocator.free(requirements);