@zappdev/runtime 0.1.0 → 0.5.0-alpha.0

package/worker.ts

@@ -1,287 +1,143 @@
-/** Options for creating a Worker or SharedWorker. */
-export interface WorkerOptions {
-  /** If true, create a shared worker that can be accessed from multiple contexts. */
-  shared?: boolean;
-  /** The `import.meta.url` of the calling module, used to resolve relative script paths. */
-  importMetaUrl?: string | URL;
+/**
+ * Worker — Zapp Workers with postMessage + named channels.
+ *
+ * @example
+ * ```ts
+ * import { Worker } from "@zappdev/runtime";
+ *
+ * const w = new Worker("./worker.ts");
+ *
+ * // Standard postMessage
+ * w.postMessage({ task: "compute" });
+ * w.onmessage = (e) => console.log(e.data);
+ *
+ * // Named channels (typed routing)
+ * w.send("compute", { n: 42 });
+ * w.receive("result", (data) => console.log(data));
+ *
+ * w.terminate();
+ * ```
+ */
+
+import { getBridge, type ZappBridge } from "./bridge";
+
+// Channel message envelope
+const CHANNEL_KEY = "__zc";
+const DATA_KEY = "d";
+
+export interface WorkerMessageEvent {
+  data: unknown;
 }
 
-type ZappBridge = {
-  createWorker: (scriptUrl: string, options?: { shared?: boolean }) => string;
-  postToWorker: (workerId: string, data: unknown) => void;
-  terminateWorker: (workerId: string) => void;
-  subscribeWorker: (
-    workerId: string,
-    onMessage?: (data: unknown) => void,
-    onError?: (data: unknown) => void,
-    onClose?: (data: unknown) => void,
-  ) => () => void;
-  resolveWorkerScriptURL?: (scriptURL: string | URL) => string;
-};
-
-function getBridge(): ZappBridge {
-  const b = (globalThis as unknown as Record<symbol, unknown>)[
-    Symbol.for("zapp.bridge")
-  ] as ZappBridge | undefined;
-  if (!b?.createWorker) {
-    throw new Error(
-      "Zapp worker bridge unavailable. " +
-      "Make sure the webview bootstrap has loaded before importing @zapp/runtime.",
-    );
-  }
-  return b;
-}
-
-function rewriteToBundledWorker(url: URL): string {
-  const ext = url.pathname.split(".").pop()?.toLowerCase();
-  if (ext !== "ts" && ext !== "tsx") return url.toString();
-  const toBundledUrl = (mappedPath: string): string => {
-    const normalized = mappedPath.startsWith("/") ? mappedPath : `/${mappedPath}`;
-    if (url.protocol === "zapp:") {
-      return `zapp://app${normalized}`;
-    }
-    return new URL(normalized, url).toString();
-  };
-  const manifest = (globalThis as unknown as Record<symbol, unknown>)[
-    Symbol.for("zapp.workerManifest")
-  ] as Record<string, string> | undefined;
-  const fileName = url.pathname.split("/").pop() ?? "worker.ts";
-  const spec = `./${fileName}`;
-  if (manifest) {
-    const mapped = manifest[spec] ?? manifest[fileName];
-    if (typeof mapped === "string" && mapped.length > 0) {
-      return toBundledUrl(mapped);
-    }
-  }
-  const pathParts = url.pathname.split("/");
-  const fallbackName = pathParts[pathParts.length - 1] ?? "worker.ts";
-  const stem = fallbackName.replace(/\.[^.]+$/, "");
-  const bundledPath = `/zapp-workers/${stem}.mjs`;
-  return toBundledUrl(bundledPath);
-}
-
-function resolveWorkerScriptURL(
-  scriptURL: string | URL,
-  importMetaUrl?: string | URL,
-): string {
-  const bridge = getBridge();
-  if (bridge.resolveWorkerScriptURL) {
-    return bridge.resolveWorkerScriptURL(scriptURL);
-  }
-  if (scriptURL instanceof URL) {
-    return rewriteToBundledWorker(scriptURL);
-  }
-  if (importMetaUrl) {
-    return rewriteToBundledWorker(new URL(scriptURL, String(importMetaUrl)));
-  }
-  return scriptURL;
-}
-
-type ListenerEntry = { listener: EventListenerOrEventListenerObject; once: boolean };
-
-/** A Zapp worker that runs a script in a separate native thread. */
 export class Worker {
   readonly id: string;
-  readonly scriptURL: string;
+  private _bridge: ZappBridge;
+  onmessage: ((event: WorkerMessageEvent) => void) | null = null;
+  onerror: ((error: unknown) => void) | null = null;
 
-  onmessage: ((event: MessageEvent) => void) | null = null;
-  onerror: ((event: ErrorEvent) => void) | null = null;
-  onclose: ((event: Event) => void) | null = null;
+  /** @internal */
+  _messageHandlers: Array<(event: WorkerMessageEvent) => void> = [];
 
-  #listeners: Record<"message" | "error" | "close", ListenerEntry[]> = {
-    message: [],
-    error: [],
-    close: [],
-  };
-  #pendingErrors: ErrorEvent[] = [];
-  #unsubscribe: (() => void) | null = null;
+  constructor(scriptUrl: string) {
+    this._bridge = getBridge();
+    this.id = (this._bridge as any).createWorker(scriptUrl);
 
-  constructor(scriptURL: string | URL, options?: WorkerOptions) {
-    const bridge = getBridge();
-    const resolved = resolveWorkerScriptURL(scriptURL, options?.importMetaUrl);
-    this.scriptURL = resolved;
-    this.id = bridge.createWorker(resolved, {
-      shared: options?.shared === true,
-    });
-    this.#unsubscribe = bridge.subscribeWorker(
-      this.id,
-      (payload) => {
-        if (payload && typeof payload === "object" && "__zapp_channel" in (payload as Record<string, unknown>)) {
-          const event = new MessageEvent("message", { data: payload });
-          this.#emit("message", event);
-          return;
-        }
-        const event = new MessageEvent("message", { data: payload });
-        this.onmessage?.(event);
-        this.#emit("message", event);
-      },
-      (payload) => {
-        const errorPayload = payload as {
-          message?: string;
-          filename?: string;
-          lineno?: number;
-          colno?: number;
-        };
-        const event = new ErrorEvent("error", {
-          message: errorPayload?.message ?? "Worker error",
-          filename: errorPayload?.filename ?? "",
-          lineno: errorPayload?.lineno ?? 0,
-          colno: errorPayload?.colno ?? 0,
-        });
-        this.#dispatchError(event);
-      },
-      () => {
-        const event = new Event("close");
-        this.onclose?.(event);
-        this.#emit("close", event);
-      },
-    );
+    // Register this instance for message dispatch
+    (this._bridge as any)._workers[this.id] = this;
   }
 
+  /** Send a raw message to the worker. */
   postMessage(data: unknown): void {
-    getBridge().postToWorker(this.id, data);
+    (this._bridge as any).postToWorker(this.id, data);
   }
 
+  /** Send a message on a named channel. */
   send(channel: string, data: unknown): void {
-    this.postMessage({ __zapp_channel: channel, data });
+    this.postMessage({ [CHANNEL_KEY]: channel, [DATA_KEY]: data });
   }
 
+  /** Listen for messages on a named channel. Returns unsubscribe function. */
   receive(channel: string, handler: (data: unknown) => void): () => void {
-    const cb = (e: Event) => {
-      const payload = (e as MessageEvent).data as Record<string, unknown>;
-      if (payload && typeof payload === "object" && payload.__zapp_channel === channel) {
-        handler(payload.data);
+    const listener = (event: WorkerMessageEvent) => {
+      const msg = event.data as Record<string, unknown>;
+      if (msg && msg[CHANNEL_KEY] === channel) {
+        handler(msg[DATA_KEY]);
       }
     };
-    this.addEventListener("message", cb);
-    return () => this.removeEventListener("message", cb);
+    this._messageHandlers.push(listener);
+    return () => {
+      this._messageHandlers = this._messageHandlers.filter(h => h !== listener);
+    };
   }
 
+  /** Terminate the worker. */
   terminate(): void {
-    if (this.#unsubscribe === null) return;
-    const unsubscribe = this.#unsubscribe;
-    this.#unsubscribe = null;
-    getBridge().terminateWorker(this.id);
-    queueMicrotask(() => unsubscribe?.());
+    (this._bridge as any).terminateWorker(this.id);
+    delete (this._bridge as any)._workers[this.id];
   }
+}
 
-  addEventListener(
-    type: string,
-    listener: EventListenerOrEventListenerObject | null,
-    options?: boolean | AddEventListenerOptions,
-  ): void {
-    if (!listener) return;
-    if (type !== "message" && type !== "error" && type !== "close") return;
-    const list = this.#listeners[type as "message" | "error" | "close"];
-    for (const entry of list) {
-      if (entry.listener === listener) return;
-    }
-    const once = typeof options === "object" && options?.once === true;
-    const signal = typeof options === "object" ? options.signal : undefined;
-    if (signal?.aborted) return;
-    list.push({ listener, once });
-    if (type === "error") this.#flushPendingErrors();
-    if (signal) {
-      const onAbort = () => this.removeEventListener(type, listener);
-      signal.addEventListener("abort", onAbort, { once: true });
-    }
-  }
+/** Port for SharedWorker communication — mirrors Worker API. */
+export class SharedWorkerPort {
+  readonly id: string;
+  private _bridge: ZappBridge;
+  onmessage: ((event: WorkerMessageEvent) => void) | null = null;
 
-  removeEventListener(
-    type: string,
-    listener: EventListenerOrEventListenerObject | null,
-  ): void {
-    if (!listener) return;
-    if (type !== "message" && type !== "error" && type !== "close") return;
-    const list = this.#listeners[type as "message" | "error" | "close"];
-    for (let i = list.length - 1; i >= 0; i -= 1) {
-      if (list[i]?.listener === listener) list.splice(i, 1);
-    }
-  }
+  /** @internal */
+  _messageHandlers: Array<(event: WorkerMessageEvent) => void> = [];
 
-  dispatchEvent(event: Event): boolean {
-    if (!event || (event.type !== "message" && event.type !== "error" && event.type !== "close")) return true;
-    this.#emit(event.type as "message" | "error" | "close", event);
-    return !event.defaultPrevented;
+  /** @internal */
+  constructor(workerId: string, bridge: ZappBridge) {
+    this.id = workerId;
+    this._bridge = bridge;
   }
 
-  #emit(type: "message" | "error" | "close", event: Event): void {
-    const list = this.#listeners[type].slice();
-    for (const entry of list) {
-      if (typeof entry.listener === "function") {
-        (entry.listener as (e: Event) => void)(event);
-      } else {
-        entry.listener.handleEvent(event);
-      }
-      if (entry.once) this.removeEventListener(type, entry.listener);
-    }
+  /** Send a raw message to the shared worker. */
+  postMessage(data: unknown): void {
+    (this._bridge as any).postToWorker(this.id, data);
   }
 
-  #dispatchError(event: ErrorEvent): void {
-    if (this.#listeners.error.length === 0 && this.onerror == null) {
-      this.#pendingErrors.push(event);
-      return;
-    }
-    this.onerror?.(event);
-    this.#emit("error", event);
+  /** Send a message on a named channel. */
+  send(channel: string, data: unknown): void {
+    this.postMessage({ [CHANNEL_KEY]: channel, [DATA_KEY]: data });
   }
 
-  #flushPendingErrors(): void {
-    if (this.#pendingErrors.length === 0) return;
-    if (this.#listeners.error.length === 0 && this.onerror == null) return;
-    const pending = this.#pendingErrors.splice(0);
-    for (const event of pending) {
-      this.onerror?.(event);
-      this.#emit("error", event);
-    }
+  /** Listen for messages on a named channel. Returns unsubscribe function. */
+  receive(channel: string, handler: (data: unknown) => void): () => void {
+    const listener = (event: WorkerMessageEvent) => {
+      const msg = event.data as Record<string, unknown>;
+      if (msg && msg[CHANNEL_KEY] === channel) {
+        handler(msg[DATA_KEY]);
+      }
+    };
+    this._messageHandlers.push(listener);
+    return () => {
+      this._messageHandlers = this._messageHandlers.filter(h => h !== listener);
+    };
   }
 }
 
-/** A shared worker accessible from multiple windows via a MessagePort-like interface. */
+/**
+ * SharedWorker — persists as long as any window holds a reference.
+ * Multiple windows creating SharedWorker with the same URL connect to the same native worker.
+ *
+ * @example
+ * ```ts
+ * const sw = new SharedWorker("./shared-worker.ts");
+ * sw.port.postMessage({ task: "sync" });
+ * sw.port.onmessage = (e) => console.log(e.data);
+ * sw.port.send("channel", data);
+ * ```
+ */
 export class SharedWorker {
-  readonly port: {
-    postMessage: (data: unknown) => void;
-    onmessage: ((event: MessageEvent) => void) | null;
-    start: () => void;
-    close: () => void;
-    addEventListener: (type: string, listener: EventListenerOrEventListenerObject) => void;
-    removeEventListener: (type: string, listener: EventListenerOrEventListenerObject) => void;
-  };
-  onerror: ((event: ErrorEvent) => void) | null = null;
-
-  readonly #inner: Worker;
-
-  constructor(scriptURL: string | URL, options?: WorkerOptions) {
-    this.#inner = new Worker(scriptURL, {
-      ...options,
-      shared: true,
-    });
+  readonly port: SharedWorkerPort;
 
-    this.port = {
-      postMessage: (data: unknown) => this.#inner.postMessage(data),
-      onmessage: null,
-      start: () => {},
-      close: () => this.#inner.terminate(),
-      addEventListener: (type: string, listener: EventListenerOrEventListenerObject) =>
-        this.#inner.addEventListener(type, listener),
-      removeEventListener: (type: string, listener: EventListenerOrEventListenerObject) =>
-        this.#inner.removeEventListener(type, listener),
-    };
-
-    this.#inner.addEventListener("message", ((e: MessageEvent) => {
-      this.port.onmessage?.(e);
-    }) as EventListener);
-
-    this.#inner.addEventListener("error", ((e: ErrorEvent) => {
-      this.onerror?.(e);
-    }) as EventListener);
-  }
-
-  send(channel: string, data: unknown): void {
-    this.#inner.send(channel, data);
-  }
+  constructor(scriptUrl: string) {
+    const bridge = getBridge();
+    const workerId = (bridge as any).createSharedWorker(scriptUrl);
+    this.port = new SharedWorkerPort(workerId, bridge);
 
-  receive(channel: string, handler: (data: unknown) => void): () => void {
-    return this.#inner.receive(channel, handler);
+    // Register port for message dispatch
+    (bridge as any)._workers[workerId] = this.port;
   }
 }

package/README.md

@@ -1,51 +0,0 @@
-# @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/bindings-contract.ts

@@ -1,31 +0,0 @@
-/** 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/protocol.ts

@@ -1,94 +0,0 @@
-/** 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;
-}