@zappdev/runtime 0.1.0 → 0.5.0-alpha.0

package/notification.ts

@@ -0,0 +1,153 @@
+/**
+ * Notification — native notifications with action buttons.
+ * Requires: app bundle + code signing (handled by `zapp dev` and `zapp package`).
+ *
+ * @example
+ * ```ts
+ * import { Notification } from "@zappdev/runtime";
+ *
+ * await Notification.requestPermission();
+ * await Notification.registerCategory({
+ *   id: "message",
+ *   actions: [{ id: "reply", title: "Reply" }, { id: "delete", title: "Delete", destructive: true }],
+ *   hasReplyField: true,
+ * });
+ * await Notification.show({ title: "New Message", body: "Hello!", categoryId: "message" });
+ * Notification.on("response", (r) => console.log(r.actionId, r.userText));
+ * ```
+ */
+
+import { getBridge } from "./bridge";
+import { Events } from "./events";
+
+export interface NotificationAction {
+  id: string;
+  title: string;
+  destructive?: boolean;
+}
+
+export interface NotificationCategory {
+  id: string;
+  actions: NotificationAction[];
+  hasReplyField?: boolean;
+  replyPlaceholder?: string;
+  replyButtonTitle?: string;
+}
+
+export interface NotificationOptions {
+  title: string;
+  subtitle?: string;
+  body?: string;
+  /** Sound: "default", "none", or custom sound name. */
+  sound?: "default" | "none" | string;
+  /** Thread ID for grouping related notifications together. */
+  threadId?: string;
+  /** Category ID for action buttons (must register category first). */
+  categoryId?: string;
+  /** Arbitrary user data (returned in response). */
+  data?: Record<string, unknown>;
+  /** File path or file:// URL for an image/audio/video attachment. */
+  attachment?: string;
+  /**
+   * Explicit notification ID. If provided, can be used to:
+   * - Update the notification later with Notification.update()
+   * - Remove it with Notification.removeDelivered()
+   * If omitted, a UUID is auto-generated.
+   */
+  id?: string;
+}
+
+export interface ScheduleOptions extends NotificationOptions {
+  trigger: { seconds: number } | { year?: number; month?: number; day?: number; hour?: number; minute?: number };
+}
+
+export interface NotificationResponse {
+  id: string;
+  actionId: string;    // "DEFAULT" for plain click, or action button ID
+  categoryId?: string;
+  userText?: string;   // if reply field was used
+}
+
+export type PermissionStatus = "granted" | "denied" | "not-determined" | "provisional";
+
+export const Notification = {
+  async requestPermission(): Promise<PermissionStatus> {
+    const result = await getBridge().invoke("__notif:requestPermission") as { status: string };
+    return result.status as PermissionStatus;
+  },
+
+  async getPermissionStatus(): Promise<PermissionStatus> {
+    const result = await getBridge().invoke("__notif:getPermission") as { status: string };
+    return result.status as PermissionStatus;
+  },
+
+  async show(options: NotificationOptions): Promise<string> {
+    const result = await getBridge().invoke("__notif:show", options as any) as { id: string };
+    return result.id;
+  },
+
+  async schedule(options: ScheduleOptions): Promise<string> {
+    const result = await getBridge().invoke("__notif:schedule", options as any) as { id: string };
+    return result.id;
+  },
+
+  async registerCategory(category: NotificationCategory): Promise<void> {
+    await getBridge().invoke("__notif:registerCategory", category as any);
+  },
+
+  async removeCategory(id: string): Promise<void> {
+    await getBridge().invoke("__notif:removeCategory", { id } as any);
+  },
+
+  async cancel(id: string): Promise<void> {
+    await getBridge().invoke("__notif:cancel", { id } as any);
+  },
+
+  async cancelAll(): Promise<void> {
+    await getBridge().invoke("__notif:cancelAll");
+  },
+
+  /** Remove a specific delivered notification from notification center. */
+  async removeDelivered(id: string): Promise<void> {
+    await getBridge().invoke("__notif:removeDelivered", { id } as any);
+  },
+
+  /** Remove all delivered notifications from notification center. */
+  async removeAllDelivered(): Promise<void> {
+    await getBridge().invoke("__notif:removeAllDelivered");
+  },
+
+  /**
+   * Update an existing notification's content (replaces by ID).
+   * The notification must have been shown with an explicit `id`.
+   */
+  async update(id: string, options: Partial<NotificationOptions>): Promise<void> {
+    await getBridge().invoke("__notif:update", { id, ...options } as any);
+  },
+
+  on(event: "click" | "action" | "response", handler: ((response: NotificationResponse) => void) | ((notificationId: string, actionId?: string) => void)): () => void {
+    if (event === "response") {
+      // Unified handler — fires for both clicks and actions
+      const offClick = Events.on("__notif:click", (payload: any) => {
+        const data = typeof payload === "string" ? JSON.parse(payload) : payload;
+        handler({ id: data.id, actionId: "DEFAULT" } as NotificationResponse);
+      });
+      const offAction = Events.on("__notif:action", (payload: any) => {
+        const data = typeof payload === "string" ? JSON.parse(payload) : payload;
+        handler({
+          id: data.id,
+          actionId: data.action,
+          userText: data.userText,
+        } as NotificationResponse);
+      });
+      return () => { offClick(); offAction(); };
+    }
+
+    // Legacy click/action handlers
+    const eventName = event === "click" ? "__notif:click" : "__notif:action";
+    return Events.on(eventName, (payload: any) => {
+      const data = typeof payload === "string" ? JSON.parse(payload) : payload;
+      handler(data.id, data.action);
+    });
+  },
+};

package/package.json

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

package/services.ts

@@ -1,91 +1,56 @@
-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;
+/**
+ * Services — call native Zen-C services from JavaScript.
+ *
+ * @example
+ * ```ts
+ * import { Services } from "@zappdev/runtime";
+ * const result = await Services.invoke("greet", { name: "World" });
+ * ```
+ */
+
+import { getBridge } from "./bridge";
+
+export interface InvokeOptions {
+  /** Timeout in milliseconds. Default: 15000. */
+  timeout?: number;
 }
 
-/** 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}`);
-    }
+export interface CancellablePromise<T> extends Promise<T> {
+  /** Cancel the pending invoke. Rejects with CancelledError. */
+  cancel(): void;
+}
 
-    if (!response.ok) {
-      const err = normalizeError(response.error);
-      throw new Error(`${err.code}: ${err.message}`);
+export const Services = {
+  /**
+   * Invoke a native service by name.
+   * In WebView/backend: async bridge call (returns CancellablePromise).
+   * In workers: sync host object call (returns resolved Promise).
+   */
+  invoke<T = unknown>(method: string, args?: Record<string, unknown>, opts?: InvokeOptions): CancellablePromise<T> {
+    // Worker/backend context: use host object for sync invocation
+    const hostBridge = (globalThis as any).__zappBridge;
+    if (hostBridge?.invokeService) {
+      const result = hostBridge.invokeService(method, args) as T;
+      const p = Promise.resolve(result) as CancellablePromise<T>;
+      p.cancel = () => {};
+      // Also expose sync result directly for worker convenience
+      (p as any).value = result;
+      return p;
     }
 
-    return response.result as T;
+    // WebView context: async bridge call
+    return getBridge().invoke(method, args, opts) as CancellablePromise<T>;
   },
 
-  getBindingsManifest(): unknown {
-    const raw = getBridge()?.getServiceBindings?.();
-    if (!raw) return null;
-    try {
-      return JSON.parse(raw);
-    } catch {
-      return null;
+  /**
+   * Invoke a native service synchronously (workers/backend only).
+   * Throws if called from WebView context.
+   */
+  invokeSync<T = unknown>(method: string, args?: Record<string, unknown>): T {
+    const hostBridge = (globalThis as any).__zappBridge;
+    if (!hostBridge?.invokeService) {
+      throw new Error("[zapp] invokeSync is only available in workers and backend contexts");
     }
+    return hostBridge.invokeService(method, args) as T;
   },
 };

package/sync.ts

@@ -1,62 +1,78 @@
-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;
-};
+/**
+ * Sync — cross-context wait/notify coordination.
+ *
+ * @example
+ * ```ts
+ * import { Sync } from "@zappdev/runtime";
+ *
+ * // In one context (window or worker):
+ * const result = await Sync.wait("data-ready", 5000);
+ * // result: "notified" | "timed-out"
+ *
+ * // In another context:
+ * Sync.notify("data-ready");
+ * ```
+ */
 
-/** 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;
-};
+import { getBridge } from "./bridge";
 
-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;
+/** Options for {@link Sync.wait}. */
+export interface SyncWaitOptions {
+  /** Timeout in milliseconds, or null/undefined to wait indefinitely. */
+  timeoutMs?: number | null;
 }
 
-/** The singleton synchronization API instance. */
-export const Sync: SyncAPI = {
+export const Sync = {
+  /**
+   * Block until the given key is notified or the timeout elapses.
+   * @param key - Sync key (non-empty string)
+   * @param timeoutOrOptions - Timeout in ms, options object, or null for indefinite
+   * @returns "notified" or "timed-out"
+   */
   async wait(
     key: string,
     timeoutOrOptions: number | SyncWaitOptions | null = 30000
   ): Promise<"notified" | "timed-out"> {
-    const bridge = getBridge();
+    const bridge = getBridge() as any;
     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,
-    });
+
+    const timeoutMs =
+      typeof timeoutOrOptions === "number"
+        ? timeoutOrOptions
+        : timeoutOrOptions?.timeoutMs ?? null;
+
+    return await bridge.syncWait(key.trim(), timeoutMs);
+  },
+
+  /**
+   * Wake up to `count` waiters blocked on the given key.
+   *
+   * Defaults to **1** — same semantics as `pthread_cond_signal` /
+   * `Object.notify()`. Use {@link Sync.notifyAll} to wake every current waiter.
+   *
+   * @param key - Sync key
+   * @param count - Number of waiters to wake (default 1)
+   */
+  notify(key: string, count = 1): void {
+    const bridge = getBridge() as any;
+    if (!bridge?.syncNotify) return;
+    if (typeof key !== "string" || key.trim().length === 0) return;
+    bridge.syncNotify(key.trim(), Math.max(1, Math.min(count, 65535)));
   },
 
-  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 });
+  /**
+   * Wake every waiter currently blocked on the given key — broadcast.
+   * Equivalent to `pthread_cond_broadcast` / `Object.notifyAll()`.
+   */
+  notifyAll(key: string): void {
+    const bridge = getBridge() as any;
+    if (!bridge?.syncNotify) return;
+    if (typeof key !== "string" || key.trim().length === 0) return;
+    bridge.syncNotify(key.trim(), 65535);
   },
 };

package/window.ts

@@ -0,0 +1,118 @@
+/**
+ * Window — per-window handle with scoped event listening.
+ *
+ * @example
+ * ```ts
+ * import { Window, WindowEvent } from "@zappdev/runtime";
+ *
+ * const win = Window.current();
+ * win.on(WindowEvent.READY, () => win.show());
+ * win.on(WindowEvent.RESIZE, (payload) => console.log(payload.size));
+ * ```
+ */
+
+import { getBridge } from "./bridge";
+import { WindowEvent, eventName, type WindowSizePayload, type WindowPayload } from "./events";
+
+/** Options for creating a window (mirrors native WindowOptions). */
+export interface WindowOptions {
+  title?: string;
+  url?: string;
+  width?: number;
+  height?: number;
+  x?: number;
+  y?: number;
+  visible?: boolean;
+  resizable?: boolean;
+  closable?: boolean;
+  minimizable?: boolean;
+  maximizable?: boolean;
+  fullscreen?: boolean;
+  borderless?: boolean;
+  transparent?: boolean;
+  alwaysOnTop?: boolean;
+  titleBarStyle?: "default" | "hidden" | "hiddenInset";
+}
+
+/** Size events that include width/height/position data. */
+type SizeEvent = WindowEvent.RESIZE | WindowEvent.MOVE | WindowEvent.MAXIMIZE | WindowEvent.RESTORE;
+
+/** A handle to a specific window. */
+export interface WindowHandle {
+  readonly id: string;
+
+  on(event: SizeEvent, handler: (payload: WindowSizePayload) => void): () => void;
+  on(event: WindowEvent, handler: (payload: WindowPayload) => void): () => void;
+
+  show(): void;
+  hide(): void;
+  close(): void;
+  setTitle(title: string): void;
+  setSize(width: number, height: number): void;
+  setPosition(x: number, y: number): void;
+  minimize(): void;
+  maximize(): void;
+  setFullscreen(on: boolean): void;
+  setAlwaysOnTop(on: boolean): void;
+  setCloseGuard(enabled: boolean): void;
+  loadUrl(url: string): void;
+}
+
+/** Send a window action to native. Uses message type 4 (WINDOW_ACTION). */
+function windowAction(action: string, args: Record<string, unknown> = {}): void {
+  const bridge = getBridge();
+  // Post raw message with t:4 for window actions (fire-and-forget)
+  const msg = JSON.stringify({ t: 4, m: action, a: args });
+  (bridge as any).post ? (bridge as any).post(msg) : bridge.emit("__window_action:" + action, args);
+}
+
+function createWindowHandle(windowId: string): WindowHandle {
+  const bridge = getBridge();
+
+  return {
+    id: windowId,
+
+    on(event: WindowEvent, handler: (payload: any) => void): () => void {
+      const name = eventName(event);
+      return bridge.on(name, (payload: any) => {
+        if (payload?.windowId === windowId) {
+          handler(payload);
+        }
+      });
+    },
+
+    show()                            { windowAction("show", { windowId }); },
+    hide()                            { windowAction("hide", { windowId }); },
+    close()                           { windowAction("close", { windowId }); },
+    setTitle(title: string)           { windowAction("setTitle", { windowId, title }); },
+    setSize(width: number, h: number) { windowAction("setSize", { windowId, width, height: h }); },
+    setPosition(x: number, y: number) { windowAction("setPosition", { windowId, x, y }); },
+    minimize()                        { windowAction("minimize", { windowId }); },
+    maximize()                        { windowAction("maximize", { windowId }); },
+    setFullscreen(on: boolean)        { windowAction("setFullscreen", { windowId, on }); },
+    setAlwaysOnTop(on: boolean)       { windowAction("setAlwaysOnTop", { windowId, on }); },
+    setCloseGuard(on: boolean)        { windowAction("setCloseGuard", { windowId, on }); },
+    loadUrl(url: string)              { windowAction("loadUrl", { windowId, url }); },
+  };
+}
+
+function getCurrentWindowId(): string | null {
+  return (globalThis as any)[Symbol.for("zapp.windowId")] ?? null;
+}
+
+export const Window = {
+  /** Get the current window handle. Only available in WebView context. */
+  current(): WindowHandle {
+    const id = getCurrentWindowId();
+    if (!id) {
+      throw new Error("[zapp] Window.current() is only available in WebView context. Use Window.create() in backend/workers.");
+    }
+    return createWindowHandle(id);
+  },
+
+  /** Create a new window. Returns a handle for the new window. */
+  async create(opts?: Partial<WindowOptions>): Promise<WindowHandle> {
+    const result = await getBridge().invoke("__window:create", opts ?? {}) as { windowId: string };
+    return createWindowHandle(result.windowId);
+  },
+};

package/worker-globals.ts

@@ -0,0 +1,47 @@
+/**
+ * Worker globals — typed declarations for Zapp Worker contexts.
+ * Import this in worker scripts for TypeScript support.
+ *
+ * @example
+ * ```ts
+ * /// <reference path="@zappdev/runtime/worker-globals" />
+ * // or
+ * import "@zappdev/runtime/worker-globals";
+ *
+ * send("channel", { data: 123 });
+ * receive("result", (data) => console.log(data));
+ * ```
+ */
+
+export {};
+
+declare global {
+  /** Send a message on a named channel to the owning WebView. */
+  function send(channel: string, data: unknown): void;
+
+  /** Listen for messages on a named channel. Returns unsubscribe function. */
+  function receive(channel: string, handler: (data: unknown) => void): () => void;
+
+  /** Post a raw message to the owning WebView. */
+  function postMessage(data: unknown): void;
+
+  /** Raw message handler — receives all messages from the WebView. */
+  var onmessage: ((event: { data: unknown }) => void) | null;
+
+  /** The native bridge — host objects for direct C calls. */
+  var __zappBridge: {
+    /** Invoke a native service synchronously. Returns the result directly. */
+    invokeService(method: string, args?: unknown): unknown;
+
+    /** Post data back to the owning WebView. */
+    postToWebview(data: unknown): void;
+
+    /** Sync wait — register a waiter on a key. */
+    syncWait(key: string, timeoutMs?: number): void;
+
+    /** Sync notify — wake waiters on a key. */
+    syncNotify(key: string, count?: number): void;
+  };
+
+  var self: typeof globalThis;
+}