@zappdev/runtime 0.1.0 → 0.6.0-alpha.0

package/app.ts

@@ -1,91 +1,38 @@
-import { Events } from "./events";
-
-/** Configuration for a Zapp application. */
-export interface AppConfig {
-  /** The display name of the application. */
-  name: string;
-  /** Whether the app should quit when its last window is closed. */
-  applicationShouldTerminateAfterLastWindowClosed: boolean;
-  /** Whether web content can be inspected via dev tools. */
-  webContentInspectable: boolean;
-  /** Maximum number of concurrent workers. */
-  maxWorkers?: number;
-}
-
-type AppBridge = {
-  getConfig?: () => AppConfig | null;
-  appAction?: (action: string, payload?: unknown) => void;
-};
-
-type ReadyCallback = () => void | Promise<void>;
-
-function getBridge(): AppBridge | null {
-  return ((globalThis as unknown as Record<symbol, unknown>)[
-    Symbol.for("zapp.bridge")
-  ] as AppBridge | undefined) ?? null;
-}
-
-function isMainContext(): boolean {
-  return (globalThis as unknown as Record<symbol, unknown>)[
-    Symbol.for("zapp.context")
-  ] !== "worker";
-}
-
-const defaultConfig: AppConfig = {
-  name: "Zapp App",
-  applicationShouldTerminateAfterLastWindowClosed: false,
-  webContentInspectable: true,
-};
-
-/** Top-level application API for lifecycle, visibility, and configuration. */
-export interface AppAPI {
-  /** Returns the current application configuration. */
-  getConfig(): AppConfig;
-  /** Registers a callback to run when the app is ready. */
-  onReady(callback: ReadyCallback): void;
-  /** Quits the application. */
-  quit(): void;
-  /** Hides the application. */
-  hide(): void;
-  /** Shows the application. */
-  show(): void;
-  /** Opens a URL in the user's default browser. */
-  openExternal(url: string): void;
-  /** Sets the application menu from a menu definition. */
-  setMenu(menu: { items: unknown[] }): void;
-}
-
-/** The singleton application API instance. */
-export const App: AppAPI = {
-  getConfig(): AppConfig {
-    return getBridge()?.getConfig?.() ?? defaultConfig;
-  },
-
-  onReady(callback: ReadyCallback): void {
-    if (!isMainContext()) {
-      console.warn("App.onReady() is only available in the main/webview context.");
-      return;
-    }
-    Events.on("ready", callback);
+/**
+ * App — application lifecycle, events, and configuration.
+ *
+ * @example
+ * ```ts
+ * import { App, AppEvent } from "@zappdev/runtime";
+ *
+ * App.on(AppEvent.REOPEN, () => console.log("dock icon clicked"));
+ * App.on(AppEvent.OPEN_URL, (data) => console.log("deep link:", data.url));
+ * App.quit();
+ * ```
+ */
+
+import { getBridge } from "./bridge";
+import { Events, AppEvent, eventName } from "./events";
+
+export const App = {
+  /** Listen for app lifecycle events. Returns unsubscribe function. */
+  on(event: AppEvent, handler: (data?: any) => void): () => void {
+    const name = eventName(event);
+    return Events.on(name, handler);
   },
 
+  /** Quit the application. */
   quit(): void {
-    getBridge()?.appAction?.("quit");
-  },
-
-  hide(): void {
-    getBridge()?.appAction?.("hide");
-  },
-
-  show(): void {
-    getBridge()?.appAction?.("show");
+    getBridge().emit("app:quit");
   },
 
+  /** Open a URL in the system browser. */
   openExternal(url: string): void {
-    getBridge()?.appAction?.("openExternal", { url });
+    (getBridge() as any).post(JSON.stringify({ t: 4, m: "openExternal", a: { url } }));
   },
 
-  setMenu(menu: { items: unknown[] }): void {
-    getBridge()?.appAction?.("setMenu", { items: menu.items });
+  /** Get the app config injected by the native bootstrap. */
+  getConfig(): Record<string, unknown> {
+    return (globalThis as any)[Symbol.for("zapp.bootstrapConfig")] ?? {};
   },
 };

package/bridge.ts

@@ -0,0 +1,23 @@
+/**
+ * Bridge accessor — internal module, not exported to users.
+ * All runtime modules talk to native through this.
+ */
+
+const BRIDGE_KEY = Symbol.for("zapp.bridge");
+
+export interface ZappBridge {
+  invoke(method: string, args?: Record<string, unknown>, opts?: { timeout?: number }): Promise<unknown> & { cancel(): void };
+  emit(name: string, payload?: Record<string, unknown>): void;
+  on(name: string, handler: (payload: unknown) => void): () => void;
+  _onInvokeResult(id: number, ok: boolean, payload: string): void;
+  _onEvent(name: string, payload: string): void;
+  dispatchWindowEvent(windowId: string, eventName: string, dataJson?: string): void;
+}
+
+export function getBridge(): ZappBridge {
+  const bridge = (globalThis as any)[BRIDGE_KEY] as ZappBridge | undefined;
+  if (!bridge) {
+    throw new Error("[zapp] Bridge not available. Is the app running in a Zapp WebView?");
+  }
+  return bridge;
+}

package/context-menu.ts

@@ -0,0 +1,84 @@
+/**
+ * ContextMenu — native context menus.
+ *
+ * @example
+ * ```ts
+ * import { ContextMenu } from "@zappdev/runtime";
+ *
+ * ContextMenu.show([
+ *     { label: "Copy", role: "copy" },
+ *     { label: "Paste", role: "paste" },
+ *     { type: "separator" },
+ *     { label: "Custom Action", action: () => console.log("clicked!") },
+ * ]);
+ * ```
+ */
+
+import { getBridge } from "./bridge";
+import { Events } from "./events";
+import type { MenuItemDef } from "./menu";
+
+let ctxActionCounter = 0;
+let lastContextX = 0;
+let lastContextY = 0;
+
+// Track right-click position
+if (typeof document !== "undefined") {
+  document.addEventListener("contextmenu", (e) => {
+    lastContextX = e.clientX;
+    lastContextY = e.clientY;
+  }, true);
+}
+
+function collectAndStrip(items: MenuItemDef[]): { clean: any[]; actions: Map<string, () => void> } {
+  const actions = new Map<string, () => void>();
+
+  function walk(items: MenuItemDef[]): any[] {
+    return items.map(item => {
+      const clean: any = { ...item };
+      if (clean.action) {
+        if (!clean.id) clean.id = `__ctx_${++ctxActionCounter}`;
+        actions.set(clean.id, clean.action);
+        delete clean.action;
+      }
+      if (clean.submenu) clean.submenu = walk(clean.submenu);
+      return clean;
+    });
+  }
+
+  return { clean: walk(items), actions };
+}
+
+export interface ContextMenuOptions {
+  /** X position in CSS pixels. Defaults to last contextmenu event position. */
+  x?: number;
+  /** Y position in CSS pixels. Defaults to last contextmenu event position. */
+  y?: number;
+}
+
+export const ContextMenu = {
+  show(items: MenuItemDef[], options?: ContextMenuOptions): void {
+    const { clean, actions } = collectAndStrip(items);
+
+    // One-shot event listener for action clicks
+    if (actions.size > 0) {
+      const off = 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();
+        off(); // One-shot: remove after first click
+      });
+
+      // Auto-cleanup after 30 seconds if no click
+      setTimeout(() => off(), 30000);
+    }
+
+    const x = options?.x ?? lastContextX;
+    const y = options?.y ?? lastContextY;
+
+    (getBridge() as any).post(JSON.stringify({
+      t: 4, m: "showContextMenu",
+      a: { items: clean, x, y }
+    }));
+  },
+};

package/dialog.ts

@@ -1,148 +1,74 @@
-import { Events } from "./events";
+/**
+ * Dialog — native file and message dialogs.
+ *
+ * @example
+ * ```ts
+ * import { Dialog } from "@zappdev/runtime";
+ *
+ * const result = await Dialog.openFile({ multiple: true, filters: [{ name: "Images", extensions: ["png", "jpg"] }] });
+ * if (!result.cancelled) console.log(result.paths);
+ *
+ * const save = await Dialog.saveFile({ defaultName: "doc.txt" });
+ * const msg = await Dialog.message({ message: "Are you sure?", buttons: ["Yes", "No"] });
+ * ```
+ */
+
+import { getBridge } from "./bridge";
 
-/** A file type filter for open/save dialogs. */
 export interface FileFilter {
-  /** Display name for the filter (e.g. "Images"). */
   name: string;
-  /** Allowed file extensions without dots (e.g. ["png", "jpg"]). */
   extensions: string[];
 }
 
-/** Options for the open-file dialog. */
 export interface OpenFileOptions {
-  /** Dialog window title. */
   title?: string;
-  /** Initial directory or file path. */
   defaultPath?: string;
-  /** File type filters shown in the dialog. */
   filters?: FileFilter[];
-  /** Whether the user can select multiple files. */
   multiple?: boolean;
-  /** Whether to select directories instead of files. */
   directory?: boolean;
 }
 
-/** Options for the save-file dialog. */
 export interface SaveFileOptions {
-  /** Dialog window title. */
   title?: string;
-  /** Initial directory path. */
   defaultPath?: string;
-  /** Default file name pre-filled in the dialog. */
   defaultName?: string;
-  /** File type filters shown in the dialog. */
   filters?: FileFilter[];
 }
 
-/** Options for a message dialog (alert/confirm). */
 export interface MessageOptions {
-  /** Dialog window title. */
-  title?: string;
-  /** The message body text. */
   message: string;
-  /** Severity level controlling the dialog icon. */
+  title?: string;
   kind?: "info" | "warning" | "critical";
-  /** Button labels to display (e.g. ["OK", "Cancel"]). */
   buttons?: string[];
 }
 
-/** Result from an open-file dialog. */
 export interface OpenFileResult {
-  /** Whether the dialog completed successfully. */
-  ok: boolean;
-  /** True if the user cancelled the dialog. */
-  cancelled?: boolean;
-  /** Selected file or directory paths. */
+  cancelled: boolean;
   paths?: string[];
 }
 
-/** Result from a save-file dialog. */
 export interface SaveFileResult {
-  /** Whether the dialog completed successfully. */
-  ok: boolean;
-  /** True if the user cancelled the dialog. */
-  cancelled?: boolean;
-  /** The chosen save path. */
+  cancelled: boolean;
   path?: string;
 }
 
-/** Result from a message dialog. */
 export interface MessageResult {
-  /** Whether the dialog completed successfully. */
-  ok: boolean;
-  /** Zero-based index of the button the user clicked. */
   button: number;
 }
 
-/** API for showing native file and message dialogs. */
-export interface DialogAPI {
-  /** Show a native open-file dialog. */
-  openFile(options?: OpenFileOptions): Promise<OpenFileResult>;
-  /** Show a native save-file dialog. */
-  saveFile(options?: SaveFileOptions): Promise<SaveFileResult>;
-  /** Show a native message dialog (alert/confirm). */
-  message(options: MessageOptions): Promise<MessageResult>;
-}
-
-let dialogSeq = 0;
-
-function assertNotWorker(): void {
-  const ctx = (globalThis as unknown as Record<symbol, unknown>)[Symbol.for("zapp.context")];
-  if (ctx === "worker") {
-    throw new Error("Dialog APIs are not available in a worker context.");
-  }
-}
-
-function postDialog<T>(action: string, params: Record<string, unknown>): Promise<T> {
-  return new Promise((resolve, reject) => {
-    const requestId = `dialog-${Date.now()}-${++dialogSeq}`;
-    const timer = setTimeout(() => {
-      off();
-      reject(new Error("Dialog timed out."));
-    }, 300000);
-
-    // Listen for the result via the bridge event system
-    const off = Events.on(`__zapp:dialog:${requestId}`, (payload) => {
-      clearTimeout(timer);
-      const result = { ...(payload as Record<string, unknown>) };
-      delete result.requestId;
-      resolve(result as T);
-    });
-
-    // Post the request to native
-    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 = `dialog\n${action}\n${JSON.stringify({ requestId, ...params })}`;
-
-    if (handler?.postMessage) {
-      handler.postMessage(msg);
-    } else if (chromeWebview?.postMessage) {
-      chromeWebview.postMessage(msg);
-    } else {
-      clearTimeout(timer);
-      off();
-      reject(new Error("Dialog bridge unavailable."));
-    }
-  });
-}
-
-/** The singleton dialog API instance. Not available in worker contexts. */
-export const Dialog: DialogAPI = {
-  openFile(options: OpenFileOptions = {}): Promise<OpenFileResult> {
-    assertNotWorker();
-    return postDialog<OpenFileResult>("openFile", options as unknown as Record<string, unknown>);
+export const Dialog = {
+  async openFile(options?: OpenFileOptions): Promise<OpenFileResult> {
+    const result = await getBridge().invoke("__dialog:open", options as any);
+    return result as OpenFileResult;
   },
 
-  saveFile(options: SaveFileOptions = {}): Promise<SaveFileResult> {
-    assertNotWorker();
-    return postDialog<SaveFileResult>("saveFile", options as unknown as Record<string, unknown>);
+  async saveFile(options?: SaveFileOptions): Promise<SaveFileResult> {
+    const result = await getBridge().invoke("__dialog:save", options as any);
+    return result as SaveFileResult;
   },
 
-  message(options: MessageOptions): Promise<MessageResult> {
-    assertNotWorker();
-    return postDialog<MessageResult>("message", options as unknown as Record<string, unknown>);
+  async message(options: MessageOptions): Promise<MessageResult> {
+    const result = await getBridge().invoke("__dialog:message", options as any);
+    return result as MessageResult;
   },
 };

package/dock.ts

@@ -0,0 +1,76 @@
+/**
+ * Dock — dock icon and badge control.
+ *
+ * @example
+ * ```ts
+ * import { Dock } from "@zappdev/runtime";
+ *
+ * Dock.setBadge("5");
+ * Dock.bounce();
+ * Dock.hideIcon();
+ * ```
+ */
+
+import { getBridge } from "./bridge";
+
+// In worker contexts, __zappBridge.dock is a sync host dispatcher that
+// calls darwin_dock_* directly. Webview fallback uses IPC-style post.
+function dockHost(): ((action: string, args?: unknown) => void) | null {
+  const host = (globalThis as any).__zappBridge;
+  return host?.dock ?? null;
+}
+
+export const Dock = {
+  /** Show the app icon in the dock/taskbar. */
+  showIcon(): void {
+    const host = dockHost();
+    if (host) { host("showIcon"); return; }
+    (getBridge() as any).post(JSON.stringify({ t: 4, m: "dock:showIcon", a: {} }));
+  },
+
+  /** Hide the app icon from the dock/taskbar. */
+  hideIcon(): void {
+    const host = dockHost();
+    if (host) { host("hideIcon"); return; }
+    (getBridge() as any).post(JSON.stringify({ t: 4, m: "dock:hideIcon", a: {} }));
+  },
+
+  /** Set a text badge on the dock icon (e.g. "5", "new"). */
+  setBadge(label: string): void {
+    const host = dockHost();
+    if (host) { host("setBadge", { label }); return; }
+    (getBridge() as any).post(JSON.stringify({ t: 4, m: "dock:setBadge", a: { label } }));
+  },
+
+  /** Remove the badge from the dock icon. */
+  removeBadge(): void {
+    const host = dockHost();
+    if (host) { host("removeBadge"); return; }
+    (getBridge() as any).post(JSON.stringify({ t: 4, m: "dock:removeBadge", a: {} }));
+  },
+
+  /** Bounce the dock icon to get user attention.
+   * @param type "informational" (bounces once) or "critical" (bounces until activated). Default: "informational"
+   */
+  bounce(type: "informational" | "critical" = "informational"): void {
+    const host = dockHost();
+    if (host) { host("bounce", { type: type === "critical" ? 1 : 0 }); return; }
+    (getBridge() as any).post(JSON.stringify({
+      t: 4, m: "dock:bounce", a: { type: type === "critical" ? 1 : 0 },
+    }));
+  },
+
+  /** Set a custom dock icon from a file path. */
+  setIcon(path: string): void {
+    const host = dockHost();
+    if (host) { host("setIcon", { path }); return; }
+    (getBridge() as any).post(JSON.stringify({ t: 4, m: "dock:setIcon", a: { path } }));
+  },
+
+  /** Reset the dock icon to the app bundle default. */
+  resetIcon(): void {
+    const host = dockHost();
+    if (host) { host("resetIcon"); return; }
+    (getBridge() as any).post(JSON.stringify({ t: 4, m: "dock:resetIcon", a: {} }));
+  },
+};