@zappdev/runtime 0.1.0 → 0.6.0-alpha.0

package/events.ts

@@ -1,249 +1,127 @@
-/** Numeric identifiers for window lifecycle and state-change events. */
+/**
+ * Events — global event bus for cross-context communication.
+ *
+ * @example
+ * ```ts
+ * import { Events } from "@zappdev/runtime";
+ *
+ * // Listen for events
+ * const off = Events.on("my-event", (data) => console.log(data));
+ *
+ * // Emit events (fire-and-forget, all listeners receive)
+ * Events.emit("my-event", { hello: "world" });
+ *
+ * // Unsubscribe
+ * off();
+ * ```
+ */
+
+import { getBridge } from "./bridge";
+
+/** Numeric identifiers for window events. */
 export enum WindowEvent {
-    /** The window has finished loading and is ready. */
-    READY = 0,
-    /** The window gained input focus. */
-    FOCUS = 1,
-    /** The window lost input focus. */
-    BLUR = 2,
-    /** The window was resized. */
-    RESIZE = 3,
-    /** The window was moved. */
-    MOVE = 4,
-    /** The window close was requested. */
-    CLOSE = 5,
-    /** The window was minimized. */
-    MINIMIZE = 6,
-    /** The window was maximized. */
-    MAXIMIZE = 7,
-    /** The window was restored from minimize or maximize. */
-    RESTORE = 8,
-    /** The window entered fullscreen mode. */
-    FULLSCREEN = 9,
-    /** The window exited fullscreen mode. */
-    UNFULLSCREEN = 10,
+  READY = 0,
+  FOCUS = 1,
+  BLUR = 2,
+  RESIZE = 3,
+  MOVE = 4,
+  CLOSE = 5,
+  MINIMIZE = 6,
+  MAXIMIZE = 7,
+  RESTORE = 8,
+  FULLSCREEN = 9,
+  UNFULLSCREEN = 10,
 }
 
-/** Numeric identifiers for application lifecycle events. */
+/** App lifecycle events.
+ * STARTED/SHUTDOWN are backend-only (fire before/after WebViews exist).
+ * The rest are available in both frontend and backend. */
 export enum AppEvent {
-    /** The application has started. */
-    STARTED = 100,
-    /** The application is shutting down. */
-    SHUTDOWN = 101,
+  STARTED = 100,       // backend-only
+  SHUTDOWN = 101,      // backend-only
+  REOPEN = 104,        // dock icon clicked
+  OPEN_URL = 105,      // deep link opened
+  DID_BECOME_ACTIVE = 106,
+  DID_RESIGN_ACTIVE = 107,
 }
 
+/** Map WindowEvent enum to string event names. */
 const WINDOW_EVENT_NAMES: Record<number, string> = {
-    [WindowEvent.READY]: "ready",
-    [WindowEvent.FOCUS]: "focus",
-    [WindowEvent.BLUR]: "blur",
-    [WindowEvent.RESIZE]: "resize",
-    [WindowEvent.MOVE]: "move",
-    [WindowEvent.CLOSE]: "close",
-    [WindowEvent.MINIMIZE]: "minimize",
-    [WindowEvent.MAXIMIZE]: "maximize",
-    [WindowEvent.RESTORE]: "restore",
-    [WindowEvent.FULLSCREEN]: "fullscreen",
-    [WindowEvent.UNFULLSCREEN]: "unfullscreen",
+  [WindowEvent.READY]: "window:ready",
+  [WindowEvent.FOCUS]: "window:focus",
+  [WindowEvent.BLUR]: "window:blur",
+  [WindowEvent.RESIZE]: "window:resize",
+  [WindowEvent.MOVE]: "window:move",
+  [WindowEvent.CLOSE]: "window:close",
+  [WindowEvent.MINIMIZE]: "window:minimize",
+  [WindowEvent.MAXIMIZE]: "window:maximize",
+  [WindowEvent.RESTORE]: "window:restore",
+  [WindowEvent.FULLSCREEN]: "window:fullscreen",
+  [WindowEvent.UNFULLSCREEN]: "window:unfullscreen",
 };
 
 const APP_EVENT_NAMES: Record<number, string> = {
-    [AppEvent.STARTED]: "app:started",
-    [AppEvent.SHUTDOWN]: "app:shutdown",
+  [AppEvent.STARTED]: "app:started",
+  [AppEvent.SHUTDOWN]: "app:shutdown",
+  [AppEvent.REOPEN]: "app:reopen",
+  [AppEvent.OPEN_URL]: "app:open-url",
+  [AppEvent.DID_BECOME_ACTIVE]: "app:active",
+  [AppEvent.DID_RESIGN_ACTIVE]: "app:inactive",
 };
 
-type EventHandler = (payload?: unknown) => void;
-
-type ZappBridge = {
-    _listeners?: Record<string, Array<{ id: number; fn: EventHandler; once?: boolean }>>;
-    _lastId?: number;
-    _emit?: (name: string, payload: unknown) => boolean;
-    _onEvent?: (name: string, handler: EventHandler) => number;
-    _offEvent?: (name: string, id: number) => void;
-    _onceEvent?: (name: string, handler: EventHandler) => number;
-    _offAllEvents?: (name?: string) => void;
-};
-
-const BRIDGE_SYMBOL = Symbol.for("zapp.bridge");
-
-const getBridge = (): ZappBridge => {
-    const bridge = (globalThis as unknown as Record<symbol, unknown>)[BRIDGE_SYMBOL] as ZappBridge | undefined;
-    if (!bridge) {
-        throw new Error("Zapp bridge is unavailable. Is the bootstrap loaded?");
-    }
-    return bridge;
-};
-
-const ensureBridge = (): ZappBridge => {
-    const symbolStore = globalThis as unknown as Record<symbol, unknown>;
-    let bridge = symbolStore[BRIDGE_SYMBOL] as ZappBridge | undefined;
-    if (!bridge) {
-        bridge = { _listeners: {}, _lastId: 0 };
-        try {
-            Object.defineProperty(symbolStore, BRIDGE_SYMBOL, {
-                value: bridge, enumerable: false, configurable: true, writable: false,
-            });
-        } catch {
-            // @ts-ignore -- fallback for non-configurable
-            symbolStore[BRIDGE_SYMBOL] = bridge;
-        }
-    }
-    if (!bridge._listeners) bridge._listeners = {};
-    return bridge;
-};
-
-/** Base payload delivered with window events. */
-export interface WindowEventPayload {
-    /** The ID of the window that emitted the event. */
-    windowId: string;
-    /** Unix-epoch millisecond timestamp of when the event occurred. */
-    timestamp: number;
-    /** Window dimensions, present on size-related events. */
-    size?: { width: number; height: number };
-    /** Window screen coordinates, present on position-related events. */
-    position?: { x: number; y: number };
+/** Payload for window events that include size and position. */
+export interface WindowSizePayload {
+  windowId: string;
+  timestamp: number;
+  size: { width: number; height: number };
+  position: { x: number; y: number };
 }
 
-/** Payload for events that always include size and position (resize, move, maximize, restore) */
-export interface WindowSizeEventPayload {
-    windowId: string;
-    timestamp: number;
-    size: { width: number; height: number };
-    position: { x: number; y: number };
+/** Payload for simple window events (focus, blur, minimize, etc). */
+export interface WindowPayload {
+  windowId: string;
+  timestamp: number;
 }
 
-// ---------------------------------------------------------------------------
-// Known event name → payload type mapping
-// ---------------------------------------------------------------------------
-
-/** Window events that carry size + position data */
-type WindowSizeEvents =
-    | "window:resize"
-    | "window:move"
-    | "window:maximize"
-    | "window:restore";
-
-/** Window events without size/position data */
-type WindowSimpleEvents =
-    | "window:ready"
-    | "window:focus"
-    | "window:blur"
-    | "window:close"
-    | "window:minimize"
-    | "window:fullscreen"
-    | "window:unfullscreen";
-
-/** App lifecycle events */
-type AppEvents =
-    | "app:started"
-    | "app:shutdown";
-
-/** All known Zapp event names */
-export type KnownEventName = WindowSizeEvents | WindowSimpleEvents | AppEvents;
+/** Known window events that carry size+position data. */
+type SizeEvents = "window:resize" | "window:move" | "window:maximize" | "window:restore";
 
-/** Resolve the payload type for a given event name */
-export type EventPayloadFor<T extends string> =
-    T extends WindowSizeEvents ? WindowSizeEventPayload :
-    T extends WindowSimpleEvents ? WindowEventPayload :
-    T extends AppEvents ? undefined :
-    unknown;
+/** Known window events without size data. */
+type SimpleEvents = "window:ready" | "window:focus" | "window:blur" | "window:close"
+  | "window:minimize" | "window:fullscreen" | "window:unfullscreen";
 
-/** Event name type — known names get autocomplete, arbitrary strings still work */
-export type EventName = KnownEventName | (string & {});
+/** App event string names. */
+type AppEvents = "app:started" | "app:shutdown" | "app:reopen" | "app:open-url" | "app:active" | "app:inactive";
 
-/** Type-safe event emitter API for subscribing to and emitting Zapp events. */
-export interface EventsAPI {
-    /** Emit a named event with an optional payload. */
-    emit(name: string, payload?: unknown): unknown;
+/** All known event names. Arbitrary strings also work. */
+export type EventName = SizeEvents | SimpleEvents | AppEvents | (string & {});
 
-    /** Subscribe to a window size/position event. Returns an unsubscribe function. */
-    on(name: WindowSizeEvents, handler: (payload: WindowSizeEventPayload) => void): () => void;
-    /** Subscribe to a simple window event. Returns an unsubscribe function. */
-    on(name: WindowSimpleEvents, handler: (payload: WindowEventPayload) => void): () => void;
-    /** Subscribe to an app lifecycle event. Returns an unsubscribe function. */
-    on(name: AppEvents, handler: () => void): () => void;
-    /** Subscribe to a custom event. Returns an unsubscribe function. */
-    on(name: string & {}, handler: (payload?: unknown) => void): () => void;
-
-    /** Subscribe to a window size/position event once. Returns an unsubscribe function. */
-    once(name: WindowSizeEvents, handler: (payload: WindowSizeEventPayload) => void): () => void;
-    /** Subscribe to a simple window event once. Returns an unsubscribe function. */
-    once(name: WindowSimpleEvents, handler: (payload: WindowEventPayload) => void): () => void;
-    /** Subscribe to an app lifecycle event once. Returns an unsubscribe function. */
-    once(name: AppEvents, handler: () => void): () => void;
-    /** Subscribe to a custom event once. Returns an unsubscribe function. */
-    once(name: string & {}, handler: (payload?: unknown) => void): () => void;
-
-    /** Remove a specific handler, or all handlers, for the given event name. */
-    off(name: EventName, handler?: EventHandler): void;
-    /** Remove all handlers for a given event name, or all events if no name is provided. */
-    offAll(name?: EventName): void;
+/** Resolve event name from enum to string. */
+export function eventName(event: WindowEvent | AppEvent): string {
+  return WINDOW_EVENT_NAMES[event] ?? APP_EVENT_NAMES[event] ?? `unknown:${event}`;
 }
 
-/** The singleton event bus for emitting, subscribing to, and removing event listeners. */
-export const Events = {
-    emit(name: string, payload?: unknown): unknown {
-        return getBridge()._emit?.(name, payload);
-    },
-
-    on(name: string, handler: EventHandler): () => void {
-        const bridge = ensureBridge();
-        if (bridge._onEvent) {
-            const id = bridge._onEvent(name, handler);
-            return () => bridge._offEvent?.(name, id);
-        }
-        const listeners = bridge._listeners!;
-        const id = (bridge._lastId = (bridge._lastId ?? 0) + 1);
-        (listeners[name] ??= []).push({ id, fn: handler });
-        return () => {
-            listeners[name] = (listeners[name] ?? []).filter((e) => e.id !== id);
-        };
-    },
-
-    once(name: string, handler: EventHandler): () => void {
-        const bridge = ensureBridge();
-        if (bridge._onceEvent) {
-            const id = bridge._onceEvent(name, handler);
-            return () => bridge._offEvent?.(name, id);
-        }
-        const listeners = bridge._listeners!;
-        const id = (bridge._lastId = (bridge._lastId ?? 0) + 1);
-        (listeners[name] ??= []).push({ id, fn: handler, once: true });
-        return () => {
-            listeners[name] = (listeners[name] ?? []).filter((e) => e.id !== id);
-        };
-    },
-
-    off(name: string, handler?: EventHandler): void {
-        const bridge = getBridge();
-        if (!handler) {
-            bridge._offAllEvents?.(name) ??
-                ((bridge._listeners ?? {})[name] = []);
-            return;
-        }
-        const listeners = bridge._listeners ?? {};
-        listeners[name] = (listeners[name] ?? []).filter((e) => e.fn !== handler);
-    },
+type EventHandler = (payload: any) => void;
 
-    offAll(name?: string): void {
-        const bridge = getBridge();
-        if (bridge._offAllEvents) {
-            bridge._offAllEvents(name);
-            return;
-        }
-        if (name) {
-            (bridge._listeners ?? {})[name] = [];
-        } else {
-            bridge._listeners = {};
-        }
-    },
-} satisfies Record<string, unknown> as EventsAPI;
-
-/** Resolve a {@link WindowEvent} enum member to its string event name. */
-export function getWindowEventName(event: WindowEvent): string {
-    return WINDOW_EVENT_NAMES[event] ?? `window:${event}`;
-}
-
-/** Resolve an {@link AppEvent} enum member to its string event name. */
-export function getAppEventName(event: AppEvent): string {
-    return APP_EVENT_NAMES[event] ?? `app:${event}`;
-}
+export const Events = {
+  /**
+   * Subscribe to an event. Returns an unsubscribe function.
+   */
+  on(name: EventName, handler: EventHandler): () => void {
+    return getBridge().on(name, handler);
+  },
+
+  /**
+   * Emit a fire-and-forget event.
+   *
+   * - From a **webview**: dispatched locally to listeners in the same window
+   *   (and to native listeners). Does not cross window boundaries.
+   * - From the **backend** worker: broadcast to *every* open webview's
+   *   listeners. This is the canonical pattern for pushing backend-owned
+   *   state to all windows without per-window polling.
+   * - From a **regular worker**: same as backend — broadcast to every webview.
+   */
+  emit(name: string, payload?: Record<string, unknown>): void {
+    getBridge().emit(name, payload);
+  },
+};

package/index.ts

@@ -1,39 +1,31 @@
 /**
  * @module
- * Frontend runtime API for Zapp desktop apps.
- *
- * Provides window management, events, dialogs, menus, workers, sync primitives,
- * and service invocation for building cross-platform desktop applications.
+ * Zapp Runtime — frontend API for Zapp desktop apps.
  *
  * @example
  * ```ts
- * import { App, Window, WindowEvent, Dialog, Menu, Events } from "@zapp/runtime";
+ * import { App, Window, WindowEvent, Events, Services } from "@zappdev/runtime";
  *
  * Window.current().on(WindowEvent.READY, () => {
  *     Window.current().show();
  * });
  *
- * const result = await Dialog.message({
- *     message: "Hello from Zapp!",
- *     buttons: ["OK"],
- * });
+ * const result = await Services.invoke("greet", { name: "World" });
  * ```
  */
 
 export { App } from "./app";
-export type { AppAPI, AppConfig } from "./app";
-export { Events, WindowEvent, AppEvent, getWindowEventName, getAppEventName } from "./events";
-export type { EventsAPI, WindowEventPayload, WindowSizeEventPayload, EventName, KnownEventName, EventPayloadFor } from "./events";
-export { Window } from "./windows";
-export type { WindowAPI, WindowOptions, WindowHandle } from "./windows";
-export { Worker, SharedWorker } from "./worker";
-export { Services } from "./services";
-export type { ServicesAPI } from "./services";
-export { Sync } from "./sync";
-export type { SyncAPI, SyncWaitOptions } from "./sync";
-export { Dialog } from "./dialog";
-export type { DialogAPI, OpenFileOptions, SaveFileOptions, MessageOptions, FileFilter, OpenFileResult, SaveFileResult, MessageResult } from "./dialog";
-export { Menu } from "./menu";
-export type { MenuAPI, MenuItemDef, MenuHandle } from "./menu";
-export * from "./protocol";
-export * from "./bindings-contract";
+export { Window, type WindowHandle, type WindowOptions } from "./window";
+export { Events, WindowEvent, AppEvent, eventName, type WindowPayload, type WindowSizePayload, type EventName } from "./events";
+export { Services, type InvokeOptions, type CancellablePromise } from "./services";
+export { Worker, SharedWorker, SharedWorkerPort, type WorkerMessageEvent } from "./worker";
+export { Dialog, type OpenFileOptions, type SaveFileOptions, type MessageOptions, type OpenFileResult, type SaveFileResult, type MessageResult } from "./dialog";
+export { Menu, type MenuItemDef, type MenuHandle } from "./menu";
+export { ContextMenu, type ContextMenuOptions } from "./context-menu";
+export { Notification, type NotificationOptions, type ScheduleOptions, type PermissionStatus } from "./notification";
+export { Sync, type SyncWaitOptions } from "./sync";
+export { Dock } from "./dock";
+
+// Re-export worker globals type declarations.
+// Workers should add: import "@zappdev/runtime/worker-globals";
+// This registers send/receive/postMessage/onmessage on the global scope.

package/menu.ts

@@ -1,98 +1,89 @@
+/**
+ * Menu — application menu bar.
+ *
+ * @example
+ * ```ts
+ * import { Menu, App } from "@zappdev/runtime";
+ *
+ * Menu.build([
+ *     { role: "appMenu" },
+ *     { label: "File", submenu: [
+ *         { label: "New", accelerator: "CmdOrCtrl+N", action: () => console.log("New!") },
+ *         { type: "separator" },
+ *         { label: "Quit", accelerator: "CmdOrCtrl+Q", action: () => App.quit() },
+ *     ]},
+ *     { label: "Edit", role: "editMenu" },
+ *     { label: "Window", role: "windowMenu" },
+ * ]);
+ * ```
+ */
+
+import { getBridge } from "./bridge";
 import { Events } from "./events";
 
-/** Definition of a single menu item, including separators, checkboxes, and submenus. */
 export interface MenuItemDef {
-  /** Unique ID for click events. Auto-generated if action is provided without id. */
   id?: string;
-  /** Display text. Required unless type is "separator" or role is set. */
   label?: string;
-  /** Item type. Default: "normal" */
   type?: "normal" | "separator" | "checkbox";
-  /** Whether the item is clickable. Default: true */
   enabled?: boolean;
-  /** For checkbox items. Default: false */
   checked?: boolean;
-  /** Keyboard shortcut. Use "CmdOrCtrl" for cross-platform Cmd/Ctrl. */
   accelerator?: string;
-  /** Built-in menu role. Overrides label/submenu with standard items. */
-  role?: "editMenu" | "windowMenu" | "appMenu";
-  /** Click handler. Sugar for menu.on(id, handler). */
+  role?: "editMenu" | "windowMenu" | "appMenu" | "copy" | "cut" | "paste" | "selectAll" | "undo" | "redo" | "quit";
   action?: () => void;
-  /** Nested submenu items. */
   submenu?: MenuItemDef[];
 }
 
-/** Handle returned after building a menu, used to listen for item clicks. */
 export interface MenuHandle {
-  /** Listen for a menu item click by its ID */
-  on(itemId: string, handler: () => void): () => void;
-  /** The raw menu definition (for re-serialization) */
   readonly items: MenuItemDef[];
 }
 
-/** API for building and installing native menus. */
-export interface MenuAPI {
-  /** Build a menu from a definition array */
-  build(items: MenuItemDef[]): MenuHandle;
-}
-
-let menuIdSeq = 0;
+let menuActionCounter = 0;
 
-type ActionEntry = { id: string; handler: () => void };
+function collectActions(items: MenuItemDef[]): Map<string, () => void> {
+  const actions = new Map<string, () => void>();
 
-function collectActions(items: MenuItemDef[], actions: ActionEntry[]): MenuItemDef[] {
-  return items.map((item) => {
-    const copy = { ...item };
-    if (copy.action && !copy.id) {
-      copy.id = `__menu_${++menuIdSeq}`;
-    }
-    if (copy.action && copy.id) {
-      actions.push({ id: copy.id, handler: copy.action });
+  function walk(items: MenuItemDef[]) {
+    for (const item of items) {
+      if (item.action) {
+        if (!item.id) {
+          item.id = `__menu_${++menuActionCounter}`;
+        }
+        actions.set(item.id, item.action);
+      }
+      if (item.submenu) walk(item.submenu);
     }
-    // Strip action from the serialized def (not JSON-serializable)
-    delete copy.action;
-    if (copy.submenu) {
-      copy.submenu = collectActions(copy.submenu, actions);
-    }
-    return copy;
-  });
-}
-
-function postMenu(items: MenuItemDef[]): void {
-  const handler = (globalThis as unknown as Record<string, Record<string, Record<string, { postMessage?: (m: string) => void }>>>)
-    .webkit?.messageHandlers?.zapp;
-  const chromeWebview = (globalThis as unknown as Record<string, Record<string, { postMessage?: (m: string) => void }>>)
-    .chrome?.webview;
+  }
 
-  const msg = `app\nsetMenu\n${JSON.stringify({ items })}`;
+  walk(items);
+  return actions;
+}
 
-  if (handler?.postMessage) {
-    handler.postMessage(msg);
-  } else if (chromeWebview?.postMessage) {
-    chromeWebview.postMessage(msg);
-  }
+function stripActions(items: MenuItemDef[]): any[] {
+  return items.map(item => {
+    const clean: any = { ...item };
+    delete clean.action;
+    if (clean.submenu) clean.submenu = stripActions(clean.submenu);
+    return clean;
+  });
 }
 
-/** The singleton menu API instance. */
-export const Menu: MenuAPI = {
+export const Menu = {
   build(items: MenuItemDef[]): MenuHandle {
-    const actions: ActionEntry[] = [];
-    const cleanItems = collectActions(items, actions);
-
-    // Post the cleaned (no functions) menu to native
-    postMenu(cleanItems);
+    const actions = collectActions(items);
+    const clean = stripActions(items);
 
-    // Wire up inline action handlers
-    const offs: (() => void)[] = [];
-    for (const { id, handler } of actions) {
-      offs.push(Events.on(`menu:${id}`, handler as () => void));
+    // Wire up action event listeners
+    if (actions.size > 0) {
+      Events.on("__menu:click", (payload: any) => {
+        const id = typeof payload === "string" ? JSON.parse(payload).id : payload?.id;
+        const handler = actions.get(id);
+        if (handler) handler();
+      });
     }
 
-    return {
-      get items() { return cleanItems; },
-      on(itemId: string, handler: () => void): () => void {
-        return Events.on(`menu:${itemId}`, handler as () => void);
-      },
-    };
+    // Send to native
+    (getBridge() as any).post(JSON.stringify({ t: 4, m: "setMenu", a: { items: clean } }));
+
+    return { items };
   },
 };