@zappdev/cli 0.5.0-alpha.9 → 0.6.0-alpha.1

package/bootstrap/codegen.ts

@@ -4,7 +4,8 @@
  *
  * Generates two functions:
  *   - zapp_webview_bootstrap_script() — WebView bridge (invoke, events, workers, sync, drag)
- *   - zapp_worker_bootstrap_script()  — Worker bridge (channels, sync dispatch)
+ *   - zapp_worker_bootstrap_script()  — Unified worker bridge (used by both webview-spawned
+ *     workers and headless workers)
  *
  * Usage: called by CLI during build, or standalone:
  *   bun bootstrap/codegen.ts [outputDir]
@@ -45,14 +46,13 @@ export async function generateBootstrap(outputDir: string): Promise<string> {
   await mkdir(outputDir, { recursive: true });
 
   // Bundle all bootstraps in parallel
-  const [webviewEscaped, workerEscaped, backendEscaped] = await Promise.all([
+  const [webviewEscaped, workerEscaped] = await Promise.all([
     bundleAndEscape(path.join(bootstrapDir, "webview.ts")),
     bundleAndEscape(path.join(bootstrapDir, "worker.ts")),
-    bundleAndEscape(path.join(bootstrapDir, "backend.ts")),
   ]);
 
   const zcContent = `// AUTO-GENERATED by zapp CLI. Do not edit.
-// Source: bootstrap/webview.ts, bootstrap/worker.ts, bootstrap/backend.ts
+// Source: bootstrap/webview.ts, bootstrap/worker.ts
 
 fn zapp_webview_bootstrap_script() -> string {
     raw { return "${webviewEscaped}"; }
@@ -63,11 +63,6 @@ fn zapp_worker_bootstrap_script() -> string {
     raw { return "${workerEscaped}"; }
     return "";
 }
-
-fn zapp_backend_bootstrap_script() -> string {
-    raw { return "${backendEscaped}"; }
-    return "";
-}
 `;
 
   const outPath = path.join(outputDir, "zapp_bootstrap.zc");

package/bootstrap/worker.ts

@@ -1,25 +1,112 @@
 /**
- * Worker bootstrap — injected into JSC worker contexts after host objects are set up.
+ * Worker bootstrap — injected into every JSC worker context (webview-spawned
+ * and headless alike). All workers share the same API surface; the only
+ * difference between a headless worker and a webview-owned one is whether
+ * they have an owner window.
  *
- * Host objects already available on __zappBridge:
+ * Host objects set up by native (see jsc_setup_bridge in jsc.m):
  *   - invokeService(method, args) → JSValue (sync, direct C call)
- *   - postToWebview(data) → void
- *   - syncWait(key, timeoutMs) → void (fires async, result via dispatchSyncResult)
- *   - syncNotify(key, count) → void
+ *   - postToWebview(data) → void (no-op in headless workers)
+ *   - syncWait(key, timeoutMs), syncNotify(key, count)
+ *   - dispatchEventToAll(name, payload) — broadcast to every webview
+ *   - createWindow(opts) → number (returns windowId; works from any worker)
+ *   - quit() — terminate the app
+ *   - showNotification(title, body)
+ *   - subscribeWindowEvent(windowId, eventId)
  *
- * This bootstrap adds JS-side convenience APIs:
- *   - self.send(channel, data) / self.receive(channel, handler) — named channels
- *   - Channel routing in _messageHandlers (called by ObjC post_message dispatch)
- *   - self.postMessage wrapper
+ * This bootstrap adds:
+ *   - A runtime bridge exposed via Symbol.for("zapp.bridge") so
+ *     @zappdev/runtime's getBridge() works uniformly across contexts.
+ *   - Channel API (self.send / self.receive) for webview-worker messaging.
+ *   - App event listener registry + _dispatchAppEvent callback for headless
+ *     workers that want to hear app:* lifecycle events.
+ *   - dispatchSyncResult glue for Sync.wait()'s promise resolution.
  */
 
 (function () {
   const bridge = (self as any).__zappBridge;
   if (!bridge) return;
 
-  // Expose under Symbol.for("zapp.bridge") so @zappdev/runtime's getBridge()
-  // works in workers. Host objects on the bridge (invokeService, syncWait,
-  // syncNotify, postToWebview, dispatchEventToAll) are accessed directly.
+  // Zero-overhead principle: we mutate __zappBridge in place to add the
+  // methods the runtime expects (on, emit, invoke, post, _onEvent,
+  // _dispatchAppEvent) and expose *that same object* under
+  // Symbol.for("zapp.bridge"). No wrapper, no indirection — when the
+  // runtime calls getBridge().invoke(...), it's hitting the native host
+  // object's own property directly.
+  //
+  // The hottest path (Services.invoke → __zappBridge.invokeService) already
+  // bypasses getBridge() entirely in runtime/services.ts, so it remains a
+  // direct C call regardless. This setup ensures the remaining
+  // runtime-API calls from worker contexts pay at most one JS property
+  // read + function call, not a whole wrapper object hop.
+
+  const listeners: Record<string, Array<(data: unknown) => void>> = {};
+
+  const windowEventIds: Record<string, number> = {
+    "window:ready": 0, "window:focus": 1, "window:blur": 2,
+    "window:resize": 3, "window:move": 4, "window:close": 5,
+    "window:minimize": 6, "window:maximize": 7, "window:restore": 8,
+    "window:fullscreen": 9, "window:unfullscreen": 10,
+  };
+
+  bridge.on = function (event: string, handler: (data: unknown) => void) {
+    if (!listeners[event]) listeners[event] = [];
+    listeners[event].push(handler);
+    const eventId = windowEventIds[event];
+    if (eventId !== undefined && typeof bridge.subscribeWindowEvent === "function") {
+      bridge.subscribeWindowEvent(-1, eventId); // -1 = all windows
+    }
+    return () => {
+      listeners[event] = (listeners[event] || []).filter((h) => h !== handler);
+    };
+  };
+
+  // Runtime's Events.emit calls bridge.emit — alias to the direct host.
+  // No wrapper, just rename.
+  bridge.emit = bridge.dispatchEventToAll;
+
+  // Runtime's getBridge().invoke() — pure alias to invokeService (zero JS
+  // overhead). Runtime APIs that need something other than a user service
+  // (Window.create, Notification.*, Dock.*) detect worker context and call
+  // the appropriate host dispatcher directly, so there's no branching here.
+  bridge.invoke = bridge.invokeService;
+
+  // Headless workers have no webview to post to; webview-owned workers
+  // use postToWebview. Alias so getBridge().post(...) works either way.
+  bridge.post = bridge.postToWebview ?? function () {};
+
+  // Native-driven event dispatch callbacks.
+  bridge._dispatchAppEvent = function (eventId: number, dataJson: string) {
+    const eventMap: Record<number, string> = {
+      100: "app:started", 101: "app:shutdown",
+      102: "app:notification-click", 103: "app:notification-action",
+      104: "app:reopen", 105: "app:open-url",
+      106: "app:active", 107: "app:inactive",
+    };
+    const name = eventMap[eventId];
+    if (!name) return;
+    let data: unknown = dataJson;
+    try { data = JSON.parse(dataJson); } catch {}
+    for (const h of listeners[name] || []) {
+      try { h(data); } catch (e) { console.error("[worker]", e); }
+    }
+    if (eventId === 102) {
+      for (const h of listeners["__notif:click"] || []) try { h(data); } catch (e) { console.error("[worker]", e); }
+    } else if (eventId === 103) {
+      for (const h of listeners["__notif:action"] || []) try { h(data); } catch (e) { console.error("[worker]", e); }
+    }
+  };
+
+  bridge._onEvent = function (name: string, payload: string) {
+    let parsed: unknown = payload;
+    try { parsed = JSON.parse(payload); } catch {}
+    for (const h of listeners[name] || []) {
+      try { h(parsed); } catch (e) { console.error("[worker]", e); }
+    }
+  };
+
+  // Expose __zappBridge itself (not a wrapper) under the symbol the
+  // runtime looks up. getBridge() returns the native host object directly.
   (globalThis as any)[Symbol.for("zapp.bridge")] = bridge;
 
   // Channel handler registry

package/dist/config.js

@@ -0,0 +1,25 @@
+// src/config.ts
+import path from "node:path";
+function defineConfig(config) {
+  return config;
+}
+async function loadConfig(root) {
+  const configPath = path.join(root, "zapp.config.ts");
+  try {
+    const mod = await import(configPath);
+    const config = typeof mod.default === "function" ? mod.default() : mod.default;
+    return {
+      ...config,
+      assetDir: config.assetDir ?? "./dist"
+    };
+  } catch {
+    return {
+      name: path.basename(root),
+      assetDir: "./dist"
+    };
+  }
+}
+export {
+  loadConfig,
+  defineConfig
+};

package/native/app/app.zc

@@ -66,10 +66,35 @@ import "../worker/engines/jsc.h" as jsc_engine;
 @cfg(ZAPP_WORKER_ENGINE_TXIKI)
 import "../worker/engines/txiki.h" as txiki_engine;
 
-@cfg(ZAPP_WORKER_ENGINE_TXIKI)
-fn app_start_backend() -> void { txiki_engine::txiki_backend_create("/_workers/backend.mjs"); }
-@cfg(ZAPP_WORKER_ENGINE_JSC)
-fn app_start_backend() -> void { jsc_engine::jsc_backend_create("/_workers/backend.mjs"); }
+// zapp_start_headless_workers is provided by .zapp/zapp_headless_workers.zc,
+// generated by the CLI from zappConfig.headless. When no headless workers are
+// configured the generated function is an empty body.
+extern fn zapp_start_headless_workers() -> void;
+
+// Helper the generated headless startup file calls for each configured worker.
+// Owner ID is empty — headless workers have no parent window.
+fn zapp_start_headless_worker(id: string, script_url: string) -> void {
+    let app = (App*)app_get_active();
+    if app == NULL { return; }
+    worker_create(app, script_url, "", id);
+}
+
+// Called from workers via the createWindow host object. Always runs on the
+// main queue (the ObjC-side dispatch_sync handles that). Builds a
+// WindowOptions and creates the window using the normal WindowManager path.
+fn zapp_worker_create_window(title: string, url: string, width: int, height: int) -> int {
+    let app = (App*)app_get_active();
+    if app == NULL { return -1; }
+    let opts = WindowOptions::create(title);
+    raw {
+        if (url && url[0] != '\0') opts.url = url;
+    }
+    if width > 0 { opts.width = width; }
+    if height > 0 { opts.height = height; }
+    opts.visible = true;
+    let win = app.window.create(&opts);
+    return win.id;
+}
 
 // Dispatch worker message to a single window by owner_id
 fn worker_dispatch_to_window(worker_id: string, data_json: string, owner_id: string) -> void {
@@ -182,7 +207,6 @@ struct AppConfig {
     webContentInspectable: ZappInspectable;
     maxWorkers: int;
     qjsStackSize: int;
-    backend: bool;  // enable backend worker (src/backend.ts)
 }
 
 // ---------------------------------------------------------------------------
@@ -247,13 +271,12 @@ impl App {
         self.window.app = (App*)self;
         app_set_active((App*)self);
 
-        // Run service startup (in registration order, before windows/backend)
+        // Run service startup (in registration order, before windows)
         service_run_startup_all();
 
-        // Start backend worker (if enabled)
-        if self.config.backend {
-            app_start_backend();
-        }
+        // Start configured headless workers. Generated function — empty body
+        // when zappConfig.headless is empty or omitted.
+        zapp_start_headless_workers();
 
         return platform_run(self.config.applicationShouldTerminateAfterLastWindowClosed);
     }

package/native/app/app_events.zc

@@ -52,7 +52,9 @@ raw {
             }
         }
 
-        // Layer 2: Backend worker (if running)
+        // Layer 2: Broadcast to every active worker (headless + webview-owned).
+        // Each worker's bootstrap sets up `_dispatchAppEvent` on __zappBridge
+        // and fans the event out to any listeners registered via bridge.on().
         {
             const char* safe_data = data ? data : "";
             char buf[4096];
@@ -62,18 +64,12 @@ raw {
                 event_id, safe_data);
 
             #if defined(ZAPP_WORKER_ENGINE_TXIKI)
-            extern bool txiki_backend_is_running(void);
-            extern void txiki_backend_eval_js(const char* js);
-            if (txiki_backend_is_running()) {
-                txiki_backend_eval_js(buf);
-            }
+            extern void txiki_broadcast_eval_js(const char* js);
+            txiki_broadcast_eval_js(buf);
             #endif
             #if defined(ZAPP_WORKER_ENGINE_JSC)
-            extern bool jsc_backend_is_running(void);
-            extern void jsc_backend_eval_js(const char* js);
-            if (jsc_backend_is_running()) {
-                jsc_backend_eval_js(buf);
-            }
+            extern void jsc_broadcast_eval_js(const char* js);
+            jsc_broadcast_eval_js(buf);
             #endif
         }
 

package/native/build.zc

@@ -37,7 +37,6 @@ fn zapp_build_accept_first_mouse() -> int { return 1; } // drag regions
 // Bootstrap stub (standalone — normally generated by CLI via bootstrap/codegen.ts)
 fn zapp_webview_bootstrap_script() -> string { return ""; }
 fn zapp_worker_bootstrap_script() -> string { return ""; }
-fn zapp_backend_bootstrap_script() -> string { return ""; }
 
 // --- Test entry point ---
 
@@ -56,7 +55,6 @@ fn main() -> int {
         webContentInspectable: Zapp::inspectable_on(),
         maxWorkers: 0,
         qjsStackSize: 0,
-        backend: false,
     };
     let app = App::new(config);
 

package/native/window/callbacks.zc

@@ -149,14 +149,13 @@ raw {
                     ename, window_id);
             }
 
+            // Broadcast to every active worker (headless + webview-owned)
             #if defined(ZAPP_WORKER_ENGINE_TXIKI)
-            extern bool txiki_backend_is_running(void);
-            extern void txiki_backend_eval_js(const char* js);
-            if (txiki_backend_is_running()) txiki_backend_eval_js(__be_buf);
+            extern void txiki_broadcast_eval_js(const char* js);
+            txiki_broadcast_eval_js(__be_buf);
             #elif defined(ZAPP_WORKER_ENGINE_JSC)
-            extern bool jsc_backend_is_running(void);
-            extern void jsc_backend_eval_js(const char* js);
-            if (jsc_backend_is_running()) jsc_backend_eval_js(__be_buf);
+            extern void jsc_broadcast_eval_js(const char* js);
+            jsc_broadcast_eval_js(__be_buf);
             #endif
             #endif
         }

package/native/worker/engines/jsc.h

@@ -24,18 +24,4 @@ void jsc_worker_terminate_owner(const char* owner_id);
 // Implemented in Zen-C (bridge/dispatch.zc), declared here for jsc.m to call.
 extern void worker_dispatch_to_webview(char* worker_id, char* data_json);
 
-// --- Backend worker (privileged, app-level JS context) ---
-
-// Create the backend worker. Loads script from path. Starts on serial queue.
-bool jsc_backend_create(const char* script_path);
-
-// Terminate the backend worker.
-void jsc_backend_terminate(void);
-
-// Evaluate JS in the backend worker context.
-void jsc_backend_eval_js(const char* js);
-
-// Check if backend worker is running.
-bool jsc_backend_is_running(void);
-
 #endif

package/native/worker/engines/jsc.m

@@ -294,6 +294,180 @@ static void jsc_setup_bridge(JSContext* ctx, NSString* workerId) {
         darwin_sync_handle("notify", [json UTF8String]);
     };
 
+    // --- Privileged host objects available in every worker ---
+
+    // quit — terminate the app from any worker
+    bridge[@"quit"] = ^{
+        dispatch_async(dispatch_get_main_queue(), ^{
+            exit(0);
+        });
+    };
+
+    // subscribeWindowEvent — register this worker for window events
+    bridge[@"subscribeWindowEvent"] = ^(JSValue* windowIdVal, JSValue* eventIdVal) {
+        int wId = [windowIdVal toInt32];
+        int eId = [eventIdVal toInt32];
+        dispatch_async(dispatch_get_main_queue(), ^{
+            extern void zapp_window_set_backend_listener(int id, int event_id, int has_listener);
+            if (wId < 0) {
+                for (int i = 0; i < 64; i++) {
+                    zapp_window_set_backend_listener(i, eId, 1);
+                }
+            } else {
+                zapp_window_set_backend_listener(wId, eId, 1);
+            }
+        });
+    };
+
+    // showNotification — fire-and-forget system notification
+    bridge[@"showNotification"] = ^(NSString* title, NSString* body) {
+        const char* t = title ? [title UTF8String] : "";
+        const char* b = body ? [body UTF8String] : "";
+        char* tc = strdup(t);
+        char* bc = strdup(b);
+        dispatch_async(dispatch_get_main_queue(), ^{
+            extern void darwin_notification_show_typed(const char*, const char*, const char*, const char*);
+            darwin_notification_show_typed(tc, "", bc, "default");
+            free(tc);
+            free(bc);
+        });
+    };
+
+    // createWindow — synchronously create a window from any worker.
+    // Dispatches to main queue (window creation requires main thread on macOS),
+    // waits for result, returns an object with windowId.
+    bridge[@"createWindow"] = ^JSValue*(JSValue* optsVal) {
+        JSContext* currentCtx = [JSContext currentContext];
+        NSString* title = @"Window";
+        NSString* url = @"";
+        __block int width = 0;
+        __block int height = 0;
+        if (optsVal && ![optsVal isUndefined] && ![optsVal isNull]) {
+            JSValue* t = optsVal[@"title"];
+            if (t && ![t isUndefined] && ![t isNull]) title = [t toString];
+            JSValue* u = optsVal[@"url"];
+            if (u && ![u isUndefined] && ![u isNull]) url = [u toString];
+            JSValue* w = optsVal[@"width"];
+            if (w && ![w isUndefined] && ![w isNull]) width = [w toInt32];
+            JSValue* h = optsVal[@"height"];
+            if (h && ![h isUndefined] && ![h isNull]) height = [h toInt32];
+        }
+        const char* titleC = strdup([title UTF8String]);
+        const char* urlC = strdup([url UTF8String]);
+        __block int windowId = -1;
+        dispatch_sync(dispatch_get_main_queue(), ^{
+            extern int zapp_worker_create_window(const char* title, const char* url, int width, int height);
+            windowId = zapp_worker_create_window(titleC, urlC, width, height);
+        });
+        free((void*)titleC);
+        free((void*)urlC);
+        JSValue* result = [JSValue valueWithNewObjectInContext:currentCtx];
+        result[@"windowId"] = [NSString stringWithFormat:@"win-%d", windowId];
+        return result;
+    };
+
+    // notif(action, args) — dispatcher for all notification operations.
+    // Runtime's Notification.* methods call this directly in worker contexts,
+    // bypassing getBridge().invoke() entirely for zero-overhead calls.
+    bridge[@"notif"] = ^JSValue*(NSString* action, JSValue* argsVal) {
+        JSContext* currentCtx = [JSContext currentContext];
+        extern const char* darwin_notification_get_permission(void);
+        extern void darwin_notification_show_typed(const char*, const char*, const char*, const char*);
+        extern void darwin_notification_schedule_typed(const char*, const char*, double);
+        extern void darwin_notification_cancel(const char*);
+        extern void darwin_notification_cancel_all(void);
+        extern void darwin_notification_remove_delivered(const char*);
+        extern void darwin_notification_remove_all_delivered(void);
+        extern void darwin_notification_update(const char*, const char*, const char*, const char*);
+
+        NSString* act = action ?: @"";
+        if ([act isEqualToString:@"getPermission"]) {
+            const char* st = darwin_notification_get_permission();
+            JSValue* r = [JSValue valueWithNewObjectInContext:currentCtx];
+            r[@"status"] = st ? [NSString stringWithUTF8String:st] : @"notDetermined";
+            return r;
+        }
+        if ([act isEqualToString:@"show"]) {
+            NSString* title = argsVal[@"title"] ? [argsVal[@"title"] toString] : @"";
+            NSString* subtitle = argsVal[@"subtitle"] ? [argsVal[@"subtitle"] toString] : @"";
+            NSString* body = argsVal[@"body"] ? [argsVal[@"body"] toString] : @"";
+            NSString* sound = argsVal[@"sound"] ? [argsVal[@"sound"] toString] : @"default";
+            darwin_notification_show_typed([title UTF8String], [subtitle UTF8String], [body UTF8String], [sound UTF8String]);
+            // Return an ID (clients use it for update/cancel). Workers don't get the native-generated ID in this
+            // sync path — generate a client-side UUID-ish value so the API contract holds.
+            JSValue* r = [JSValue valueWithNewObjectInContext:currentCtx];
+            r[@"id"] = [NSString stringWithFormat:@"notif-%llu-%u", (unsigned long long)[[NSDate date] timeIntervalSince1970] * 1000, arc4random()];
+            return r;
+        }
+        if ([act isEqualToString:@"schedule"]) {
+            NSString* title = argsVal[@"title"] ? [argsVal[@"title"] toString] : @"";
+            NSString* body = argsVal[@"body"] ? [argsVal[@"body"] toString] : @"";
+            double delay = argsVal[@"delaySeconds"] ? [argsVal[@"delaySeconds"] toDouble] : 0;
+            darwin_notification_schedule_typed([title UTF8String], [body UTF8String], delay);
+            JSValue* r = [JSValue valueWithNewObjectInContext:currentCtx];
+            r[@"id"] = [NSString stringWithFormat:@"notif-%llu-%u", (unsigned long long)[[NSDate date] timeIntervalSince1970] * 1000, arc4random()];
+            return r;
+        }
+        if ([act isEqualToString:@"cancel"]) {
+            NSString* id_ = argsVal[@"id"] ? [argsVal[@"id"] toString] : @"";
+            darwin_notification_cancel([id_ UTF8String]);
+            return [JSValue valueWithUndefinedInContext:currentCtx];
+        }
+        if ([act isEqualToString:@"cancelAll"]) {
+            darwin_notification_cancel_all();
+            return [JSValue valueWithUndefinedInContext:currentCtx];
+        }
+        if ([act isEqualToString:@"removeDelivered"]) {
+            NSString* id_ = argsVal[@"id"] ? [argsVal[@"id"] toString] : @"";
+            darwin_notification_remove_delivered([id_ UTF8String]);
+            return [JSValue valueWithUndefinedInContext:currentCtx];
+        }
+        if ([act isEqualToString:@"removeAllDelivered"]) {
+            darwin_notification_remove_all_delivered();
+            return [JSValue valueWithUndefinedInContext:currentCtx];
+        }
+        if ([act isEqualToString:@"update"]) {
+            NSString* id_ = argsVal[@"id"] ? [argsVal[@"id"] toString] : @"";
+            NSString* title = argsVal[@"title"] ? [argsVal[@"title"] toString] : @"";
+            NSString* subtitle = argsVal[@"subtitle"] ? [argsVal[@"subtitle"] toString] : @"";
+            NSString* body = argsVal[@"body"] ? [argsVal[@"body"] toString] : @"";
+            darwin_notification_update([id_ UTF8String], [title UTF8String], [subtitle UTF8String], [body UTF8String]);
+            return [JSValue valueWithUndefinedInContext:currentCtx];
+        }
+        return [JSValue valueWithUndefinedInContext:currentCtx];
+    };
+
+    // dock(action, args) — dispatcher for all dock operations. All are sync,
+    // fire-and-forget (they post to the main UI thread internally via the
+    // Zen-C bridge and return immediately).
+    bridge[@"dock"] = ^(NSString* action, JSValue* argsVal) {
+        extern void darwin_dock_show_icon(void);
+        extern void darwin_dock_hide_icon(void);
+        extern void darwin_dock_set_badge(const char*);
+        extern void darwin_dock_remove_badge(void);
+        extern void darwin_dock_bounce(int);
+        extern void darwin_dock_set_icon(const char*);
+        extern void darwin_dock_reset_icon(void);
+
+        NSString* act = action ?: @"";
+        if ([act isEqualToString:@"showIcon"]) { darwin_dock_show_icon(); return; }
+        if ([act isEqualToString:@"hideIcon"]) { darwin_dock_hide_icon(); return; }
+        if ([act isEqualToString:@"setBadge"]) {
+            NSString* label = argsVal[@"label"] ? [argsVal[@"label"] toString] : @"";
+            darwin_dock_set_badge([label UTF8String]); return;
+        }
+        if ([act isEqualToString:@"removeBadge"]) { darwin_dock_remove_badge(); return; }
+        if ([act isEqualToString:@"bounce"]) {
+            int t = argsVal[@"type"] ? [argsVal[@"type"] toInt32] : 0;
+            darwin_dock_bounce(t); return;
+        }
+        if ([act isEqualToString:@"setIcon"]) {
+            NSString* p = argsVal[@"path"] ? [argsVal[@"path"] toString] : @"";
+            darwin_dock_set_icon([p UTF8String]); return;
+        }
+        if ([act isEqualToString:@"resetIcon"]) { darwin_dock_reset_icon(); return; }
+    };
+
     ctx[@"__zappBridge"] = bridge;
 
     // setTimeout / setInterval
@@ -555,165 +729,21 @@ void jsc_worker_terminate_owner(const char* owner_id) {
     }
 }
 
-// --- Backend worker (privileged, app-level JS context) ---
-// JSC first. txiki.js opt-in later for web APIs (fetch, WebSocket, timers).
-
-static JSContext* jsc_backend_ctx = nil;
-static dispatch_queue_t jsc_backend_queue = nil;
-static BOOL jsc_backend_running = NO;
-
-bool jsc_backend_create(const char* script_path) {
-    if (jsc_backend_running) return false;
-    if (!script_path) return false;
-    jsc_ensure_init();
-
-    NSString* scriptPath = [NSString stringWithUTF8String:script_path];
-    jsc_backend_queue = dispatch_queue_create("com.zapp.backend", DISPATCH_QUEUE_SERIAL);
-
-    dispatch_async(jsc_backend_queue, ^{
-        JSContext* ctx = [[JSContext alloc] initWithVirtualMachine:jsc_vm];
-        ctx.name = @"Zapp Backend";
-        ctx.exceptionHandler = ^(JSContext* c, JSValue* exception) {
-            (void)c;
-            NSLog(@"[backend ERROR] %@", exception);
-        };
-
-        // Make inspectable
-        if (app_get_bootstrap_web_content_inspectable()) {
-            if ([ctx respondsToSelector:@selector(setInspectable:)]) {
-                [ctx setInspectable:YES];
-            }
-        }
-
-        // Set up standard bridge (console, invokeService, syncWait/Notify)
-        jsc_setup_bridge(ctx, @"__backend__");
-
-        // Backend-specific host objects
-        JSValue* bridge = ctx[@"__zappBridge"];
-
-        // quit — terminate the app
-        bridge[@"quit"] = ^{
-            dispatch_async(dispatch_get_main_queue(), ^{
-                exit(0);
-            });
-        };
-
-        // subscribeWindowEvent — register backend for window events
-        bridge[@"subscribeWindowEvent"] = ^(JSValue* windowIdVal, JSValue* eventIdVal) {
-            int wid = [windowIdVal toInt32];
-            int eid = [eventIdVal toInt32];
-            dispatch_async(dispatch_get_main_queue(), ^{
-                extern void zapp_window_set_backend_listener(int id, int event_id, int has_listener);
-                if (wid < 0) {
-                    // Subscribe all windows (wid == -1)
-                    for (int i = 0; i < 64; i++) {
-                        zapp_window_set_backend_listener(i, eid, 1);
-                    }
-                } else {
-                    zapp_window_set_backend_listener(wid, eid, 1);
-                }
-            });
-        };
-
-        // showNotification — fire-and-forget
-        bridge[@"showNotification"] = ^(NSString* title, NSString* body) {
-            const char* t = title ? [title UTF8String] : "";
-            const char* b = body ? [body UTF8String] : "";
-            // Copy strings for async block
-            char* tc = strdup(t);
-            char* bc = strdup(b);
-            dispatch_async(dispatch_get_main_queue(), ^{
-                extern void darwin_notification_show_typed(const char*, const char*, const char*, const char*);
-                darwin_notification_show_typed(tc, "", bc, "default");
-                free(tc);
-                free(bc);
-            });
-        };
-
-        jsc_backend_ctx = ctx;
-
-        // Load backend bootstrap
-        extern const char* zapp_backend_bootstrap_script(void);
-        const char* bootstrap = zapp_backend_bootstrap_script();
-        if (bootstrap && bootstrap[0] != '\0') {
-            [ctx evaluateScript:[NSString stringWithUTF8String:bootstrap]];
-        }
-
-        // Load user backend script — try embedded first, then filesystem.
-        // scriptPath is the canonical URL form ("/_workers/backend.mjs").
-        NSString* script = nil;
-
-        extern int zapp_build_use_embedded_assets(void);
-        extern int zapp_embedded_assets_count;
-        extern ZappEmbeddedAsset zapp_embedded_assets[];
-        if (zapp_build_use_embedded_assets() && zapp_embedded_assets_count > 0) {
-            for (int ai = 0; ai < zapp_embedded_assets_count; ai++) {
-                NSString* assetPath = [NSString stringWithUTF8String:zapp_embedded_assets[ai].path];
-                if ([assetPath isEqualToString:scriptPath]) {
-                    if (zapp_embedded_assets[ai].is_brotli && zapp_embedded_assets[ai].uncompressed_len > 0) {
-                        uint8_t* out = malloc(zapp_embedded_assets[ai].uncompressed_len + 1);
-                        size_t decoded = compression_decode_buffer(
-                            out, zapp_embedded_assets[ai].uncompressed_len,
-                            zapp_embedded_assets[ai].data, zapp_embedded_assets[ai].len,
-                            NULL, COMPRESSION_BROTLI);
-                        out[decoded] = '\0';
-                        script = [[NSString alloc] initWithBytesNoCopy:out length:decoded
-                            encoding:NSUTF8StringEncoding freeWhenDone:YES];
-                    } else {
-                        script = [[NSString alloc] initWithBytes:zapp_embedded_assets[ai].data
-                            length:zapp_embedded_assets[ai].len encoding:NSUTF8StringEncoding];
-                    }
-                    NSLog(@"[zapp] backend loaded from embedded: %@", scriptPath);
-                    break;
-                }
-            }
-        }
-
-        if (!script) {
-            // Dev: Vite plugin writes workers to .zapp/workers/<basename>
-            char cwd[1024];
-            NSString* base = getcwd(cwd, sizeof(cwd)) ? [NSString stringWithUTF8String:cwd] : @".";
-            NSString* basename = [scriptPath lastPathComponent];
-            NSString* fullPath = [[base stringByAppendingPathComponent:@".zapp/workers"]
-                stringByAppendingPathComponent:basename];
-            NSError* err = nil;
-            script = [NSString stringWithContentsOfFile:fullPath encoding:NSUTF8StringEncoding error:&err];
-            if (script) NSLog(@"[zapp] backend worker started: %@", fullPath);
-            else NSLog(@"[zapp] backend script not found: %@", fullPath);
-        }
-
-        if (script) {
-            // Async IIFE wrapper enables top-level await — see jsc_worker_create
-            // for rationale.
-            NSString* wrapped = [NSString stringWithFormat:
-                @"(async () => {\n%@\n})().catch(e => { console.error('[backend error]', e && e.stack ? e.stack : e); });",
-                script];
-            [ctx evaluateScript:wrapped withSourceURL:[NSURL URLWithString:@"backend.mjs"]];
-        }
-    });
-
-    jsc_backend_running = YES;
-    return true;
-}
-
-void jsc_backend_terminate(void) {
-    if (!jsc_backend_running) return;
-    jsc_backend_ctx = nil;
-    jsc_backend_queue = nil;
-    jsc_backend_running = NO;
-    NSLog(@"[zapp] backend worker terminated");
-}
-
-void jsc_backend_eval_js(const char* js) {
-    if (!jsc_backend_running || !jsc_backend_ctx || !jsc_backend_queue || !js) return;
+// Broadcast a JS snippet to every active worker (headless + webview-owned).
+// Used by native event dispatch to deliver app/window events to every worker
+// that may have subscribed. Each worker evaluates on its own serial queue.
+void jsc_broadcast_eval_js(const char* js) {
+    if (!js) return;
     NSString* script = [NSString stringWithUTF8String:js];
-    dispatch_async(jsc_backend_queue, ^{
-        if (jsc_backend_ctx) {
-            [jsc_backend_ctx evaluateScript:script];
-        }
-    });
+    for (int i = 0; i < JSC_MAX_WORKERS; i++) {
+        if (!jsc_workers[i].active) continue;
+        NSString* wid = [NSString stringWithUTF8String:jsc_workers[i].worker_id];
+        dispatch_queue_t queue = jsc_queues[wid];
+        JSContext* ctx = jsc_contexts[wid];
+        if (!queue || !ctx) continue;
+        dispatch_async(queue, ^{
+            [ctx evaluateScript:script];
+        });
+    }
 }
 
-bool jsc_backend_is_running(void) {
-    return jsc_backend_running;
-}

package/native/worker/engines/txiki.c

@@ -945,13 +945,9 @@ static void* txiki_backend_thread(void* arg) {
     JS_FreeValue(ctx, bridge);
     JS_FreeValue(ctx, global);
 
-    // Load backend bootstrap
-    extern const char* zapp_backend_bootstrap_script(void);
-    const char* bootstrap = zapp_backend_bootstrap_script();
-    if (bootstrap && bootstrap[0] != '\0') {
-        JSValue r = JS_Eval(ctx, bootstrap, strlen(bootstrap), "<backend-bootstrap>", JS_EVAL_TYPE_GLOBAL);
-        JS_FreeValue(ctx, r);
-    }
+    // Note: dead code path — app_start_backend no longer dispatches here.
+    // Backend bootstrap was merged into the worker bootstrap; this function
+    // is left in place until the full txiki backend removal lands.
 
     // Load user backend script — try embedded first, then filesystem.
     // slot->script_url is the canonical URL form ("/_workers/backend.mjs").
@@ -1085,3 +1081,14 @@ void txiki_backend_eval_js(const char* js) {
 bool txiki_backend_is_running(void) {
     return txiki_backend_running != 0;
 }
+
+// Broadcast a JS snippet to every active worker. Counterpart of
+// jsc_broadcast_eval_js — used by native event dispatch to deliver app and
+// window events to every worker. TODO: txiki uses a message-queue/libuv
+// dispatch pattern rather than direct eval; a full implementation requires
+// adding an "eval this JS" message type handled in on_async_message. For now
+// this is a stub so the JSC engine path works; txiki headless workers will
+// not receive forwarded events until this is wired up.
+void txiki_broadcast_eval_js(const char* js) {
+    (void)js;
+}

package/package.json

@@ -1,22 +1,26 @@
 {
   "name": "@zappdev/cli",
-  "version": "0.5.0-alpha.9",
+  "version": "0.6.0-alpha.1",
   "type": "module",
   "bin": {
     "zapp": "./src/zapp-cli.ts"
   },
   "exports": {
-    "./config": "./src/config.ts"
+    "./config": {
+      "types": "./src/config.ts",
+      "default": "./dist/config.js"
+    }
   },
   "files": [
     "src/",
+    "dist/",
     "native/",
     "bootstrap/",
     "assets/",
     "vendor/webview2/"
   ],
   "scripts": {
-    "prepack": "cp -r ../native ./native && cp -r ../bootstrap ./bootstrap && cp -r ../assets ./assets && mkdir -p ./vendor && cp -r ../vendor/webview2 ./vendor/webview2",
+    "prepack": "bun build src/config.ts --outdir dist --format esm --target node && cp -r ../native ./native && cp -r ../bootstrap ./bootstrap && cp -r ../assets ./assets && mkdir -p ./vendor && cp -r ../vendor/webview2 ./vendor/webview2",
     "postpack": "rm -rf ./native ./bootstrap ./assets ./vendor"
   },
   "dependencies": {

package/src/build-config.ts

@@ -52,6 +52,35 @@ fn zapp_build_accept_first_mouse() -> int { return ${config.macos?.acceptFirstMo
   return outPath;
 }
 
+// Generate .zapp/zapp_headless_workers.zc — the function native/app/app.zc
+// declares as `extern fn zapp_start_headless_workers()`. Body contains one
+// call per entry in zappConfig.headless; empty body when no headless workers
+// are configured.
+export async function generateHeadlessWorkers(opts: { root: string; headless?: Record<string, string> }): Promise<string> {
+  const { root, headless } = opts;
+  const zappDir = path.join(root, ".zapp");
+  await mkdir(zappDir, { recursive: true });
+
+  const entries = Object.entries(headless ?? {});
+  const calls = entries
+    .map(([id]) => `    zapp_start_headless_worker("h-${id}", "/_workers/_headless_${id}.mjs");`)
+    .join("\n");
+
+  const body = calls || `    // No headless workers configured.`;
+
+  const content = `// AUTO-GENERATED by zapp CLI. Do not edit.
+// Implementation for native/app/app.zc's extern fn zapp_start_headless_workers().
+
+fn zapp_start_headless_workers() -> void {
+${body}
+}
+`;
+
+  const outPath = path.join(zappDir, "zapp_headless_workers.zc");
+  await Bun.write(outPath, content);
+  return outPath;
+}
+
 // Generate .zapp/zapp_platform.zc with .m file cflags
 export async function generatePlatformConfig(root: string, buildFile?: string): Promise<string> {
   const zappDir = path.join(root, ".zapp");

package/src/config.ts

@@ -26,7 +26,12 @@ export interface ZappConfig {
   version?: string;
   assetDir?: string;  // Default: "./dist" (Vite), configurable for static sites
   devPort?: number;   // Default: 5173
-  backend?: string;   // Path to backend worker source (e.g. "src/server.ts"). Omit for no backend.
+  /**
+   * Headless workers to start at app boot, keyed by ID.
+   * Example: `{ db: "src/workers/db.ts", sync: "src/workers/sync.ts" }`
+   * IDs are used for termination via `Workers.terminate(id)`.
+   */
+  headless?: Record<string, string>;
   deepLinkSchemes?: string[];  // e.g. ["myapp"] → registers myapp:// URL scheme
   macos?: MacOSConfig;
   security?: SecurityConfig;

package/src/init.ts

@@ -56,7 +56,6 @@ fn run_app() -> int {
         webContentInspectable: Zapp::inspectable_auto(),
         maxWorkers: 0,
         qjsStackSize: 0,
-        backend: false,
     };
     let app = App::new(config);
     app.service.add("greet", greet);
@@ -110,6 +109,12 @@ export default defineConfig({
   name: "${name}",
   identifier: "${identifier}",
   version: "0.1.0",
+  // Add headless TypeScript workers that start when the app boots.
+  // Keys are worker IDs (used for termination); values are source paths.
+  //
+  //   headless: {
+  //     db: "src/workers/db.ts",
+  //   },
 });
 `);
 
@@ -127,12 +132,12 @@ export default defineConfig({
 
   pkgObj.dependencies = {
     ...(pkgObj.dependencies ?? {}),
-    "@zappdev/runtime": "^0.5.0-alpha.0",
+    "@zappdev/runtime": "^0.6.0-alpha.0",
   };
   pkgObj.devDependencies = {
     ...(pkgObj.devDependencies ?? {}),
-    "@zappdev/cli": "^0.5.0-alpha.0",
-    "@zappdev/vite": "^0.5.0-alpha.0",
+    "@zappdev/cli": "^0.6.0-alpha.0",
+    "@zappdev/vite": "^0.6.0-alpha.0",
   };
 
   await Bun.write(pkgPath, JSON.stringify(pkgObj, null, 2));
@@ -171,7 +176,7 @@ export default defineConfig({
     if (!viteConfig.includes("zappWorkers(")) {
       viteConfig = viteConfig.replace(
         /plugins:\s*\[/,
-        "plugins: [zappWorkers({ backend: zappConfig.backend }), "
+        "plugins: [zappWorkers({ headless: zappConfig.headless }), "
       );
     }
 
@@ -183,7 +188,7 @@ import { zappWorkers } from "@zappdev/vite";
 import zappConfig from "./zapp.config";
 
 export default defineConfig({
-  plugins: [zappWorkers({ backend: zappConfig.backend })],
+  plugins: [zappWorkers({ headless: zappConfig.headless })],
 });
 `);
   }

package/src/native.ts

@@ -91,13 +91,14 @@ interface CompileOptions {
   buildConfigFile: string;   // .zapp/zapp_build_config.zc
   bootstrapFile?: string;    // .zapp/zapp_bootstrap.zc
   assetsFile?: string;       // .zapp/zapp_assets.zc (embedded brotli assets)
+  headlessFile?: string;     // .zapp/zapp_headless_workers.zc
   output: string;            // Binary output path
   nativeDir: string;         // Framework source dir
   optimize: boolean;         // Size optimizations
 }
 
 export async function compileNative(opts: CompileOptions): Promise<void> {
-  const { root, buildFile, buildConfigFile, bootstrapFile, assetsFile, output, nativeDir, optimize } = opts;
+  const { root, buildFile, buildConfigFile, bootstrapFile, assetsFile, headlessFile, output, nativeDir, optimize } = opts;
 
   // Generate platform config with .m file paths
   const { generatePlatformConfig } = await import("./build-config");
@@ -112,6 +113,7 @@ export async function compileNative(opts: CompileOptions): Promise<void> {
     platformFile,
     ...(bootstrapFile ? [bootstrapFile] : []),
     ...(assetsFile ? [assetsFile] : []),
+    ...(headlessFile ? [headlessFile] : []),
     "-I", nativeDir,
     "-o", output,
     // Suppress C compiler warnings by default. The framework and zc stdlib

package/src/zapp-cli.ts

@@ -4,7 +4,7 @@ import process from "node:process";
 import { mkdir } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import { loadConfig } from "./config";
-import { generateBuildConfig, generatePlatformConfig } from "./build-config";
+import { generateBuildConfig, generatePlatformConfig, generateHeadlessWorkers } from "./build-config";
 import { generateBindings } from "./generate";
 import { compileNative, ensureTxikiBuilt, hasTxikiEnabled, hasAnyWorkerEngine } from "./native";
 import { resolveNativeDir, resolveBootstrapDir } from "./paths";
@@ -71,6 +71,7 @@ async function runDev(root: string) {
   // 3. Generate build config + bootstrap (dev mode)
   const buildConfigFile = await generateBuildConfig({ root, config, mode: "dev", devUrl });
   const platformFile = await generatePlatformConfig(root);
+  const headlessFile = await generateHeadlessWorkers({ root, headless: config.headless });
   const zappDir = path.join(root, ".zapp");
   process.stdout.write("[zapp] generating bootstrap...\n");
   const bootstrapFile = await generateBootstrap(zappDir);
@@ -137,6 +138,7 @@ async function runDev(root: string) {
     buildConfigFile,
     bootstrapFile,
     assetsFile,
+    headlessFile,
     output: nativeOut,
     nativeDir,
     optimize: false,
@@ -260,6 +262,7 @@ async function runBuild(root: string) {
   // 5. Generate build config + bootstrap (prod mode, embedded assets)
   const buildConfigFile = await generateBuildConfig({ root, config, mode: "prod", embedAssets: true });
   const platformFile = await generatePlatformConfig(root);
+  const headlessFile = await generateHeadlessWorkers({ root, headless: config.headless });
   const bootstrapFile = await generateBootstrap(zappDir);
 
   // 5. Compile native binary (assets embedded in binary)
@@ -276,6 +279,7 @@ async function runBuild(root: string) {
     buildConfigFile,
     bootstrapFile,
     assetsFile,
+    headlessFile,
     output: nativeOut,
     nativeDir,
     optimize: true,

package/bootstrap/backend.ts

@@ -1,139 +0,0 @@
-/**
- * Backend worker bootstrap — injected into the privileged backend JS context.
- *
- * Sets up event dispatch and the `Zapp` global for user-friendly API.
- * Host objects available on __zappBridge:
- *   - invokeService(method, args) → JSValue
- *   - syncWait(key, timeoutMs), syncNotify(key, count)
- *   - showNotification(title, body)
- *   - createWindow(opts)
- *   - quit()
- *
- * JSC only for now. txiki.js opt-in later for web APIs (fetch, WebSocket, timers).
- */
-
-(function () {
-  const bridge = (self as any).__zappBridge;
-  if (!bridge) return;
-
-  const listeners: Record<string, Array<(data: unknown) => void>> = {};
-
-  // Event registration
-  bridge.on = function (event: string, handler: (data: unknown) => void) {
-    if (!listeners[event]) listeners[event] = [];
-    listeners[event].push(handler);
-    return () => {
-      listeners[event] = (listeners[event] || []).filter((h) => h !== handler);
-    };
-  };
-
-  // Called by native when app events fire (via jsc_backend_eval_js)
-  bridge._dispatchAppEvent = function (eventId: number, dataJson: string) {
-    const eventMap: Record<number, string> = {
-      100: "app:started",
-      101: "app:shutdown",
-      102: "app:notification-click",
-      103: "app:notification-action",
-      104: "app:reopen",
-      105: "app:open-url",
-      106: "app:active",
-      107: "app:inactive",
-    };
-    const name = eventMap[eventId];
-    if (!name) return;
-    let data: unknown = dataJson;
-    try {
-      data = JSON.parse(dataJson);
-    } catch {}
-    const handlers = listeners[name] || [];
-    for (let i = 0; i < handlers.length; i++) {
-      try {
-        handlers[i](data);
-      } catch (e) {
-        console.error("[backend]", e);
-      }
-    }
-
-    // Also dispatch notification events under __notif: names
-    // so Notification.on("click"/"action") from @zappdev/runtime works
-    if (eventId === 102) {
-      const notifHandlers = listeners["__notif:click"] || [];
-      for (const h of notifHandlers) try { h(data); } catch (e) { console.error("[backend]", e); }
-    } else if (eventId === 103) {
-      const notifHandlers = listeners["__notif:action"] || [];
-      for (const h of notifHandlers) try { h(data); } catch (e) { console.error("[backend]", e); }
-    }
-  };
-
-  // Window event name → event ID mapping (for backend subscription)
-  const windowEventIds: Record<string, number> = {
-    "window:ready": 0, "window:focus": 1, "window:blur": 2,
-    "window:resize": 3, "window:move": 4, "window:close": 5,
-    "window:minimize": 6, "window:maximize": 7, "window:restore": 8,
-    "window:fullscreen": 9, "window:unfullscreen": 10,
-  };
-
-  // Expose as Symbol.for('zapp.bridge') so @zappdev/runtime works in the backend.
-  // The runtime's getBridge() looks for this symbol on globalThis.
-  const runtimeBridge = {
-    on(name: string, handler: (data: unknown) => void) {
-      const off = bridge.on(name, handler);
-
-      // If subscribing to a window event, tell native to forward to backend
-      const eventId = windowEventIds[name];
-      if (eventId !== undefined && bridge.subscribeWindowEvent) {
-        // Subscribe all windows (pass -1 for "all")
-        bridge.subscribeWindowEvent(-1, eventId);
-      }
-
-      return off;
-    },
-    emit(name: string, payload?: Record<string, unknown>) {
-      // Broadcast to every webview via the native dispatchEventToAll bridge.
-      // Each webview's bridge._onEvent picks it up and fans out to listeners
-      // registered with Events.on(name, ...).
-      if (typeof bridge.dispatchEventToAll === "function") {
-        bridge.dispatchEventToAll(name, payload ?? {});
-      }
-    },
-    invoke(method: string, args?: Record<string, unknown>) {
-      // Use host object for sync service invocation
-      const result = bridge.invokeService(method, args);
-      return Promise.resolve(result);
-    },
-    post(msg: string) {
-      // No WebView to post to — no-op in backend
-    },
-    // Sync primitives — forward to the native host objects so Sync.wait /
-    // Sync.notify work from the backend the same way they work in workers.
-    syncWait(key: string, timeoutMs?: number | null) {
-      if (typeof bridge.syncWait !== "function") {
-        throw new Error("Sync bridge is unavailable.");
-      }
-      return bridge.syncWait(key, timeoutMs ?? -1);
-    },
-    syncNotify(key: string, count?: number) {
-      if (typeof bridge.syncNotify !== "function") return;
-      bridge.syncNotify(key, count ?? 1);
-    },
-    // Called by native Layer 3 when dispatching window events to backend
-    _onEvent(name: string, payload: string) {
-      const handlers = listeners[name] || [];
-      let parsed: unknown = payload;
-      try { parsed = JSON.parse(payload); } catch {}
-      for (let i = 0; i < handlers.length; i++) {
-        try { handlers[i](parsed); } catch (e) { console.error("[backend]", e); }
-      }
-    },
-  };
-  (globalThis as any)[Symbol.for("zapp.bridge")] = runtimeBridge;
-
-  // Convenience global — the user-facing API (legacy, still works)
-  (self as any).Zapp = {
-    on: bridge.on,
-    invokeService: bridge.invokeService,
-    createWindow: bridge.createWindow,
-    showNotification: bridge.showNotification,
-    quit: bridge.quit,
-  };
-})();