@zappdev/runtime 0.1.0

package/README.md

@@ -0,0 +1,51 @@
+# @zapp/runtime
+
+Frontend runtime API for Zapp desktop apps. Provides type-safe access to native window management, events, dialogs, menus, services, and more from your web frontend.
+
+## Install
+
+```sh
+bun add @zapp/runtime
+```
+
+```sh
+npm install @zapp/runtime
+```
+
+## Usage
+
+```ts
+import { App, Window, Events, Dialog, Menu } from "@zapp/runtime";
+
+// Listen for window events
+Events.on("window:resize", (payload) => {
+  console.log("Window resized:", payload.width, payload.height);
+});
+
+// Open a file dialog
+const result = await Dialog.openFile({
+  title: "Select a file",
+  filters: [{ name: "Images", extensions: ["png", "jpg"] }],
+});
+
+// Create a new window
+await Window.open({ title: "My Window", width: 800, height: 600 });
+```
+
+## Features
+
+- **Window management** -- create, resize, move, and close native windows
+- **Event system** -- subscribe to window and app lifecycle events
+- **Dialogs** -- native open/save file dialogs and message boxes
+- **Menus** -- build native application and context menus
+- **Services** -- communicate with backend services
+- **Workers** -- spawn Web Workers and Shared Workers with native integration
+- **Sync primitives** -- cross-thread synchronization utilities
+
+## Docs
+
+See the full documentation in [`../../docs/`](../../docs/).
+
+## License
+
+MIT

package/app.ts

@@ -0,0 +1,91 @@
+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);
+  },
+
+  quit(): void {
+    getBridge()?.appAction?.("quit");
+  },
+
+  hide(): void {
+    getBridge()?.appAction?.("hide");
+  },
+
+  show(): void {
+    getBridge()?.appAction?.("show");
+  },
+
+  openExternal(url: string): void {
+    getBridge()?.appAction?.("openExternal", { url });
+  },
+
+  setMenu(menu: { items: unknown[] }): void {
+    getBridge()?.appAction?.("setMenu", { items: menu.items });
+  },
+};

package/bindings-contract.ts

@@ -0,0 +1,31 @@
+/** Current version of the bindings schema format. */
+export const ZAPP_BINDINGS_SCHEMA_VERSION = 1;
+
+/** Describes a single method exposed by a service binding. */
+export type ZappServiceBindingMethod = {
+  name: string;
+  requestType?: string;
+  responseType?: string;
+  capability?: string;
+};
+
+/** Describes a service and the methods it exposes. */
+export type ZappServiceBinding = {
+  name: string;
+  namespace?: string;
+  methods: ZappServiceBindingMethod[];
+};
+
+/** Top-level manifest listing all available service bindings. */
+export type ZappBindingsManifest = {
+  v: typeof ZAPP_BINDINGS_SCHEMA_VERSION;
+  generatedAt: string;
+  services: ZappServiceBinding[];
+};
+
+/** Create an empty bindings manifest with the current schema version. */
+export const emptyBindingsManifest = (): ZappBindingsManifest => ({
+  v: ZAPP_BINDINGS_SCHEMA_VERSION,
+  generatedAt: new Date().toISOString(),
+  services: [],
+});

package/dialog.ts

@@ -0,0 +1,148 @@
+import { Events } from "./events";
+
+/** 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. */
+  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. */
+  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. */
+  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>);
+  },
+
+  saveFile(options: SaveFileOptions = {}): Promise<SaveFileResult> {
+    assertNotWorker();
+    return postDialog<SaveFileResult>("saveFile", options as unknown as Record<string, unknown>);
+  },
+
+  message(options: MessageOptions): Promise<MessageResult> {
+    assertNotWorker();
+    return postDialog<MessageResult>("message", options as unknown as Record<string, unknown>);
+  },
+};

package/events.ts

@@ -0,0 +1,249 @@
+/** Numeric identifiers for window lifecycle and state-change 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,
+}
+
+/** Numeric identifiers for application lifecycle events. */
+export enum AppEvent {
+    /** The application has started. */
+    STARTED = 100,
+    /** The application is shutting down. */
+    SHUTDOWN = 101,
+}
+
+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",
+};
+
+const APP_EVENT_NAMES: Record<number, string> = {
+    [AppEvent.STARTED]: "app:started",
+    [AppEvent.SHUTDOWN]: "app:shutdown",
+};
+
+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 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 };
+}
+
+// ---------------------------------------------------------------------------
+// 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;
+
+/** 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;
+
+/** Event name type — known names get autocomplete, arbitrary strings still work */
+export type EventName = KnownEventName | (string & {});
+
+/** 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;
+
+    /** 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;
+}
+
+/** 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);
+    },
+
+    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}`;
+}

package/index.ts

@@ -0,0 +1,39 @@
+/**
+ * @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.
+ *
+ * @example
+ * ```ts
+ * import { App, Window, WindowEvent, Dialog, Menu, Events } from "@zapp/runtime";
+ *
+ * Window.current().on(WindowEvent.READY, () => {
+ *     Window.current().show();
+ * });
+ *
+ * const result = await Dialog.message({
+ *     message: "Hello from Zapp!",
+ *     buttons: ["OK"],
+ * });
+ * ```
+ */
+
+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";