@zappdev/runtime 0.1.0

package/menu.ts

@@ -0,0 +1,98 @@
+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). */
+  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;
+
+type ActionEntry = { id: string; handler: () => 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 });
+    }
+    // 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 })}`;
+
+  if (handler?.postMessage) {
+    handler.postMessage(msg);
+  } else if (chromeWebview?.postMessage) {
+    chromeWebview.postMessage(msg);
+  }
+}
+
+/** The singleton menu API instance. */
+export const Menu: MenuAPI = {
+  build(items: MenuItemDef[]): MenuHandle {
+    const actions: ActionEntry[] = [];
+    const cleanItems = collectActions(items, actions);
+
+    // Post the cleaned (no functions) menu to native
+    postMenu(cleanItems);
+
+    // Wire up inline action handlers
+    const offs: (() => void)[] = [];
+    for (const { id, handler } of actions) {
+      offs.push(Events.on(`menu:${id}`, handler as () => void));
+    }
+
+    return {
+      get items() { return cleanItems; },
+      on(itemId: string, handler: () => void): () => void {
+        return Events.on(`menu:${itemId}`, handler as () => void);
+      },
+    };
+  },
+};

package/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "@zappdev/runtime",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Frontend runtime API for Zapp desktop apps",
+  "main": "index.ts",
+  "types": "index.ts",
+  "files": [
+    "*.ts",
+    "src/"
+  ],
+  "license": "MIT"
+}

package/protocol.ts

@@ -0,0 +1,94 @@
+/** Current version of the worker wire protocol. */
+export const ZAPP_WORKER_PROTOCOL_VERSION = 1;
+/** Current version of the service invocation protocol. */
+export const ZAPP_SERVICE_PROTOCOL_VERSION = 1;
+
+/** Discriminator strings for worker control messages. */
+export type ZappWorkerControlType =
+  | "zapp:worker:init"
+  | "zapp:worker:post"
+  | "zapp:worker:message"
+  | "zapp:worker:error"
+  | "zapp:worker:terminate";
+
+/** Envelope wrapping all worker control messages on the wire. */
+export interface ZappWorkerEnvelope<T = unknown> {
+  v: typeof ZAPP_WORKER_PROTOCOL_VERSION;
+  t: ZappWorkerControlType;
+  workerId: string;
+  payload?: T;
+}
+
+/** Payload for the worker init control message. */
+export interface ZappWorkerInitPayload {
+  scriptUrl: string;
+  shared?: boolean;
+}
+
+/** Payload for posting data to a worker. */
+export interface ZappWorkerPostPayload {
+  data: unknown;
+}
+
+/** Payload for a message received from a worker. */
+export interface ZappWorkerMessagePayload {
+  data: unknown;
+}
+
+/** Payload describing a worker error. */
+export interface ZappWorkerErrorPayload {
+  message: string;
+  stack?: string;
+  filename?: string;
+  lineno?: number;
+  colno?: number;
+}
+
+/** Host-side bridge interface for managing workers from the native layer. */
+export type ZappWorkerHostBridge = {
+  createWorker(scriptUrl: string, options?: { shared?: boolean }): string;
+  postToWorker(workerId: string, data: unknown): void;
+  terminateWorker(workerId: string): void;
+  subscribe(
+    workerId: string,
+    onMessage: (data: unknown) => void,
+    onError: (error: ZappWorkerErrorPayload) => void,
+  ): () => void;
+};
+
+/** Standard error codes returned by service invocations. */
+export type ZappServiceErrorCode =
+  | "BAD_REQUEST"
+  | "INVALID_METHOD"
+  | "UNAUTHORIZED"
+  | "NOT_FOUND"
+  | "INTERNAL_ERROR"
+  | "TIMEOUT";
+
+/** A request to invoke a named service method. */
+export interface ZappServiceInvokeRequest {
+  v: typeof ZAPP_SERVICE_PROTOCOL_VERSION;
+  id: string;
+  method: string;
+  args: unknown;
+  meta: {
+    sourceCtxId: string;
+    capability?: string;
+  };
+}
+
+/** Structured error returned from a failed service invocation. */
+export interface ZappServiceInvokeError {
+  code: ZappServiceErrorCode;
+  message: string;
+  details?: unknown;
+}
+
+/** Response envelope from a service invocation. */
+export interface ZappServiceInvokeResponse {
+  v: typeof ZAPP_SERVICE_PROTOCOL_VERSION;
+  id: string;
+  ok: boolean;
+  result?: unknown;
+  error?: ZappServiceInvokeError;
+}

package/services.ts

@@ -0,0 +1,91 @@
+import {
+  ZAPP_SERVICE_PROTOCOL_VERSION,
+  type ZappServiceInvokeError,
+  type ZappServiceInvokeRequest,
+  type ZappServiceInvokeResponse,
+} from "./protocol";
+
+type Bridge = {
+  invoke?: (req: ZappServiceInvokeRequest) => Promise<ZappServiceInvokeResponse>;
+  getServiceBindings?: () => string | null;
+};
+
+const getBridge = (): Bridge | null =>
+  ((globalThis as unknown as Record<symbol, unknown>)[
+    Symbol.for("zapp.bridge")
+  ] as Bridge | undefined) ?? null;
+
+const normalizeError = (error: unknown): ZappServiceInvokeError => {
+  if (error && typeof error === "object") {
+    const errObj = error as Record<string, unknown>;
+    if (typeof errObj.code === "string" && typeof errObj.message === "string") {
+      return {
+        code: errObj.code as ZappServiceInvokeError["code"],
+        message: errObj.message,
+        details: errObj.details,
+      };
+    }
+  }
+  if (error instanceof Error) {
+    return { code: "INTERNAL_ERROR", message: error.message };
+  }
+  return { code: "INTERNAL_ERROR", message: "Service invocation failed" };
+};
+
+const makeRequest = (method: string, args: unknown): ZappServiceInvokeRequest => ({
+  v: ZAPP_SERVICE_PROTOCOL_VERSION,
+  id: `svc-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+  method,
+  args,
+  meta: {
+    sourceCtxId: `ctx-${Math.random().toString(36).slice(2)}`,
+  },
+});
+
+/** API for invoking native services defined in the Zapp backend. */
+export interface ServicesAPI {
+  /** Call a named service method and return the result. */
+  invoke<T = unknown>(method: string, args?: unknown): Promise<T>;
+  /** Retrieve the parsed bindings manifest describing available services, or null. */
+  getBindingsManifest(): unknown;
+}
+
+/** The singleton services API instance. */
+export const Services: ServicesAPI = {
+  async invoke<T = unknown>(method: string, args?: unknown): Promise<T> {
+    if (typeof method !== "string" || method.length === 0) {
+      throw new Error("Service method must be a non-empty string.");
+    }
+
+    const bridge = getBridge();
+    if (!bridge?.invoke) {
+      throw new Error("Native invoke bridge is unavailable.");
+    }
+
+    const req = makeRequest(method, args ?? {});
+    let response: ZappServiceInvokeResponse;
+    try {
+      response = await bridge.invoke(req);
+    } catch (error) {
+      const normalized = normalizeError(error);
+      throw new Error(`${normalized.code}: ${normalized.message}`);
+    }
+
+    if (!response.ok) {
+      const err = normalizeError(response.error);
+      throw new Error(`${err.code}: ${err.message}`);
+    }
+
+    return response.result as T;
+  },
+
+  getBindingsManifest(): unknown {
+    const raw = getBridge()?.getServiceBindings?.();
+    if (!raw) return null;
+    try {
+      return JSON.parse(raw);
+    } catch {
+      return null;
+    }
+  },
+};

package/sync.ts

@@ -0,0 +1,62 @@
+type Bridge = {
+  syncWait?: (request: {
+    key: string;
+    timeoutMs: number | null;
+    signal?: AbortSignal;
+  }) => Promise<"notified" | "timed-out">;
+  syncNotify?: (request: { key: string; count: number }) => boolean;
+  syncCancel?: (request: { id: string }) => boolean;
+};
+
+/** Options for {@link SyncAPI.wait}. */
+export type SyncWaitOptions = {
+  /** Timeout in milliseconds, or null to wait indefinitely. */
+  timeoutMs?: number | null;
+  /** An AbortSignal to cancel the wait. */
+  signal?: AbortSignal;
+};
+
+const getBridge = (): Bridge | null =>
+  ((globalThis as unknown as Record<symbol, unknown>)[
+    Symbol.for("zapp.bridge")
+  ] as Bridge | undefined) ?? null;
+
+/** API for cross-context synchronization primitives (wait/notify). */
+export interface SyncAPI {
+  /** Block until the given key is notified or the timeout elapses. */
+  wait(key: string, timeoutOrOptions?: number | SyncWaitOptions | null): Promise<"notified" | "timed-out">;
+  /** Wake up to `count` waiters blocked on the given key. */
+  notify(key: string, count?: number): boolean;
+}
+
+/** The singleton synchronization API instance. */
+export const Sync: SyncAPI = {
+  async wait(
+    key: string,
+    timeoutOrOptions: number | SyncWaitOptions | null = 30000
+  ): Promise<"notified" | "timed-out"> {
+    const bridge = getBridge();
+    if (!bridge?.syncWait) {
+      throw new Error("Sync bridge is unavailable.");
+    }
+    if (typeof key !== "string" || key.trim().length === 0) {
+      throw new Error("Sync key must be a non-empty string.");
+    }
+    const options: SyncWaitOptions =
+      typeof timeoutOrOptions === "number" || timeoutOrOptions == null
+        ? { timeoutMs: timeoutOrOptions }
+        : timeoutOrOptions;
+    return await bridge.syncWait({
+      key: key.trim(),
+      timeoutMs: options.timeoutMs ?? null,
+      signal: options.signal,
+    });
+  },
+
+  notify(key: string, count = 1): boolean {
+    const bridge = getBridge();
+    if (!bridge?.syncNotify) return false;
+    if (typeof key !== "string" || key.trim().length === 0) return false;
+    return bridge.syncNotify({ key: key.trim(), count });
+  },
+};

package/windows.ts

@@ -0,0 +1,222 @@
+import { Events, WindowEvent, getWindowEventName, type WindowEventPayload, type WindowSizeEventPayload } from "./events";
+
+/** Options for creating a new window. */
+export interface WindowOptions {
+  /** Window title text. */
+  title?: string;
+  /** Initial width in logical pixels. */
+  width?: number;
+  /** Initial height in logical pixels. */
+  height?: number;
+  /** Initial x position on screen. */
+  x?: number;
+  /** Initial y position on screen. */
+  y?: number;
+  /** URL to load in the window. */
+  url?: string;
+  /** Whether the window can be resized by the user. */
+  resizable?: boolean;
+  /** Whether the window shows a close button. */
+  closable?: boolean;
+  /** Whether the window can be minimized. */
+  minimizable?: boolean;
+  /** Whether the window can be maximized. */
+  maximizable?: boolean;
+  /** Whether the window starts in fullscreen. */
+  fullscreen?: boolean;
+  /** Whether the window floats above other windows. */
+  alwaysOnTop?: boolean;
+  /** Title bar appearance style. */
+  titleBarStyle?: "default" | "hidden" | "hiddenInset";
+  /** Whether the window is visible on creation. */
+  visible?: boolean;
+}
+
+/** Window events that carry size + position */
+type SizeEvent =
+  | WindowEvent.RESIZE
+  | WindowEvent.MOVE
+  | WindowEvent.MAXIMIZE
+  | WindowEvent.RESTORE;
+
+/** Handle for controlling an individual window instance. */
+export type WindowHandle = {
+  /** Unique identifier for this window. */
+  readonly id: string;
+  /** Show the window. */
+  show(): void;
+  /** Hide the window. */
+  hide(): void;
+  /** Minimize the window. */
+  minimize(): void;
+  /** Maximize the window. */
+  maximize(): void;
+  /** Restore the window from minimized state. */
+  unminimize(): void;
+  /** Restore the window from maximized state. */
+  unmaximize(): void;
+  /** Toggle between minimized and restored. */
+  toggleMinimize(): void;
+  /** Toggle between maximized and restored. */
+  toggleMaximize(): void;
+  /** Request the window to close (may be intercepted by close guards). */
+  close(): void;
+  /** Set the window title. */
+  setTitle(title: string): void;
+  /** Set the window size in logical pixels. */
+  setSize(width: number, height: number): void;
+  /** Set the window position on screen. */
+  setPosition(x: number, y: number): void;
+  /** Enter or exit fullscreen mode. */
+  setFullscreen(on: boolean): void;
+  /** Set whether the window floats above other windows. */
+  setAlwaysOnTop(on: boolean): void;
+  /** Force-close the window, bypassing all close guards */
+  destroy(): void;
+  /** Typed event listener — size events get a payload with size + position */
+  on(event: SizeEvent, handler: (payload: WindowSizeEventPayload) => void): () => void;
+  /** Typed event listener — other window events get base payload */
+  on(event: WindowEvent, handler: (payload: WindowEventPayload) => void): () => void;
+  /** Typed one-time listener — size events */
+  once(event: SizeEvent, handler: (payload: WindowSizeEventPayload) => void): () => void;
+  /** Typed one-time listener — other window events */
+  once(event: WindowEvent, handler: (payload: WindowEventPayload) => void): () => void;
+  /** Remove all listeners for an event */
+  off(event: WindowEvent): void;
+};
+
+type WindowBridge = {
+  windowCreate?: (options: WindowOptions) => Promise<{ id: string }>;
+  windowAction?: (windowId: string, action: string, params?: Record<string, unknown>) => void;
+};
+
+const getBridge = (): WindowBridge | null =>
+  ((globalThis as unknown as Record<symbol, unknown>)[
+    Symbol.for("zapp.bridge")
+  ] as WindowBridge | undefined) ?? null;
+
+function makeHandle(windowId: string): WindowHandle {
+  const action = (name: string, params?: Record<string, unknown>) => {
+    const bridge = getBridge();
+    bridge?.windowAction?.(windowId, name, params);
+  };
+
+  const isWindowReady = (): boolean => {
+    const ss = globalThis as unknown as Record<symbol, unknown>;
+    return ss[Symbol.for("zapp.windowReady")] === true;
+  };
+
+  let closeListenerCount = 0;
+
+  const handleOn = (event: WindowEvent, handler: (payload: WindowEventPayload) => void): (() => void) => {
+    const eventName = getWindowEventName(event);
+    const off = Events.on(`window:${eventName}`, (payload) => {
+      const p = payload as WindowEventPayload | undefined;
+      if (p?.windowId === windowId) {
+        handler(p);
+      }
+    });
+
+    // Auto-guard: registering a CLOSE listener enables the native close guard
+    if (event === WindowEvent.CLOSE) {
+      closeListenerCount++;
+      if (closeListenerCount === 1) {
+        action("setCloseGuard", { guard: true });
+      }
+    }
+
+    if (event === WindowEvent.READY && isWindowReady()) {
+      queueMicrotask(() => handler({ windowId, timestamp: Date.now() }));
+    }
+
+    // Return unsubscribe that also manages the close guard
+    return () => {
+      off();
+      if (event === WindowEvent.CLOSE) {
+        closeListenerCount--;
+        if (closeListenerCount <= 0) {
+          closeListenerCount = 0;
+          action("setCloseGuard", { guard: false });
+        }
+      }
+    };
+  };
+
+  const handleOnce = (event: WindowEvent, handler: (payload: WindowEventPayload) => void): (() => void) => {
+    if (event === WindowEvent.READY && isWindowReady()) {
+      queueMicrotask(() => handler({ windowId, timestamp: Date.now() }));
+      return () => {};
+    }
+    const eventName = getWindowEventName(event);
+    return Events.once(`window:${eventName}`, (payload) => {
+      const p = payload as WindowEventPayload | undefined;
+      if (p?.windowId === windowId) {
+        handler(p);
+      }
+    });
+  };
+
+  const handleOff: WindowHandle["off"] = (event: WindowEvent) => {
+    const eventName = getWindowEventName(event);
+    Events.off(`window:${eventName}`);
+  };
+
+  return {
+    get id() { return windowId; },
+    show() { action("show"); },
+    hide() { action("hide"); },
+    minimize() { action("minimize"); },
+    maximize() { action("maximize"); },
+    unminimize() { action("unminimize"); },
+    unmaximize() { action("unmaximize"); },
+    toggleMinimize() { action("toggle_minimize"); },
+    toggleMaximize() { action("toggle_maximize"); },
+    close() { action("close"); },
+    destroy() { action("destroy"); },
+    setTitle(title: string) { action("set_title", { title }); },
+    setSize(width: number, height: number) { action("set_size", { width, height }); },
+    setPosition(x: number, y: number) { action("set_position", { x, y }); },
+    setFullscreen(on: boolean) { action("set_fullscreen", { on }); },
+    setAlwaysOnTop(on: boolean) { action("set_always_on_top", { on }); },
+    on: handleOn as WindowHandle["on"],
+    once: handleOnce as WindowHandle["once"],
+    off: handleOff,
+  };
+}
+
+/** API for creating and accessing windows. */
+export interface WindowAPI {
+  /** Create a new window with the given options. */
+  create(options?: WindowOptions): Promise<WindowHandle>;
+  /** Get a handle to the current webview's window. Throws in worker contexts. */
+  current(): WindowHandle;
+}
+
+/** The singleton window management API instance. */
+export const Window: WindowAPI = {
+  async create(options: WindowOptions = {}): Promise<WindowHandle> {
+    const bridge = getBridge();
+    if (!bridge?.windowCreate) {
+      throw new Error("Window bridge unavailable. Is the Zapp runtime loaded?");
+    }
+    const result = await bridge.windowCreate(options);
+    return makeHandle(result.id);
+  },
+
+  current(): WindowHandle {
+    const symbolStore = globalThis as unknown as Record<symbol, unknown>;
+    if (symbolStore[Symbol.for("zapp.context")] === "worker") {
+      throw new Error("Window.current() is not available in a worker context. Use Window.create() instead.");
+    }
+    const windowId = symbolStore[Symbol.for("zapp.windowId")] as string | undefined;
+    const ownerId = symbolStore[Symbol.for("zapp.ownerId")] as string | undefined;
+    const contextWindowId = symbolStore[Symbol.for("zapp.currentWindowId")] as string | undefined;
+    const id = windowId ?? contextWindowId ?? ownerId;
+    if (!id) {
+      throw new Error(
+        "Window.current() is only available in a webview context with an associated window.",
+      );
+    }
+    return makeHandle(id);
+  },
+};