mygo-runtime 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MyGo contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,30 @@
+# mygo-runtime
+
+Typed access to the runtime of [MyGo](https://github.com/egoist/mygo) apps,
+for their web frontends.
+
+MyGo injects its runtime into every page of an app as `window.mygo`. This
+package gives it types and imports. The client that `mygo generate` writes
+for your bound Go services is built on it, so you mostly use that:
+
+```ts
+import { Greeter, events } from "./mygo"; // generated
+
+const greeting = await Greeter.greet("Ada");
+events.tick.on((time) => console.log(time));
+```
+
+Use the package directly for the window and the platform:
+
+```ts
+import { currentWindow, isCallError, isMyGo, runtime } from "mygo-runtime";
+
+if (isMyGo() && runtime().platform === "darwin") {
+  document.body.classList.add("mac");
+}
+await currentWindow.toggleMaximize();
+```
+
+A Go method returning an error rejects with a `CallError` (see
+`isCallError`). Outside a MyGo window, e.g. when the dev server is opened in a
+browser, calls reject and `isMyGo()` is false.

package/dist/index.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Typed access to the MyGo runtime, which MyGo injects into every page of
+ * an app as `window.mygo`. The client that `mygo generate` writes for your Go
+ * services is built on it; use it directly for window controls and the
+ * platform:
+ *
+ * ```ts
+ * import { currentWindow, runtime } from "mygo-runtime";
+ *
+ * if (runtime().platform === "darwin") document.body.classList.add("mac");
+ * await currentWindow.toggleMaximize();
+ * ```
+ *
+ * @module
+ */
+import type { Runtime, WindowControls } from "./types";
+export type { Platform, Runtime, WindowControls } from "./types";
+declare global {
+    interface Window {
+        /** The MyGo runtime; missing outside MyGo windows. */
+        mygo?: Runtime;
+    }
+}
+/** Reports whether the page runs inside a MyGo window. */
+export declare function isMyGo(): boolean;
+/**
+ * Returns the MyGo runtime. Throws when the page is not running inside a
+ * MyGo window, e.g. when the dev server is opened in a regular browser.
+ */
+export declare function runtime(): Runtime;
+/**
+ * Calls a bound Go method by name, e.g. `call("Greeter.Greet", "Ada")`.
+ * Prefer the typed client generated by `mygo generate`. A Go error rejects
+ * with a {@link CallError}.
+ */
+export declare function call<T = unknown>(method: string, ...args: unknown[]): Promise<T>;
+/** Subscribes to a Go event by name. Returns a function that unsubscribes. */
+export declare function on<T = unknown>(name: string, listener: (payload: T) => void): () => void;
+/** Like {@link on}, but unsubscribes after the first event. */
+export declare function once<T = unknown>(name: string, listener: (payload: T) => void): () => void;
+/** A typed event sent by the Go side, declared with `mygo.NewEvent`. */
+export interface GoEvent<T> {
+    readonly name: string;
+    /** Subscribes to the event and returns a function that unsubscribes. */
+    on(listener: (payload: T) => void): () => void;
+    /** Like on, but unsubscribes after the first event. */
+    once(listener: (payload: T) => void): () => void;
+}
+/** Returns the typed event `name`; the generated client declares them. */
+export declare function event<T>(name: string): GoEvent<T>;
+/** The error of a call whose Go method returned an error. */
+export interface CallError extends Error {
+    readonly name: "CallError";
+    /** The method that failed, e.g. "Greeter.Greet". */
+    readonly method: string;
+}
+/** Reports whether err comes from a Go method that returned an error. */
+export declare function isCallError(err: unknown): err is CallError;
+/** Files dropped on the window, e.g. from Finder or Explorer. */
+export interface FileDrop {
+    /** Absolute paths of the dropped files and directories. */
+    paths: string[];
+    /** Where they were dropped, in CSS pixels, like `clientX`. */
+    x: number;
+    /** Where they were dropped, in CSS pixels, like `clientY`. */
+    y: number;
+}
+/**
+ * Subscribes to files dropped on the window, with their paths, which DOM
+ * drop events do not tell. Only the app's own pages get them. Returns a
+ * function that unsubscribes.
+ *
+ * ```ts
+ * onFileDrop(({ paths, x, y }) => {
+ *   const target = document.elementFromPoint(x, y);
+ * });
+ * ```
+ */
+export declare function onFileDrop(listener: (drop: FileDrop) => void): () => void;
+/** The window hosting the page, e.g. for a custom title bar. */
+export declare const currentWindow: WindowControls;

package/dist/index.js

@@ -0,0 +1,57 @@
+// src/index.ts
+function isMyGo() {
+  return typeof globalThis === "object" && globalThis.mygo !== undefined;
+}
+function runtime() {
+  const rt = globalThis.mygo;
+  if (!rt)
+    throw new Error("mygo: runtime not found; is this page running inside a MyGo window?");
+  return rt;
+}
+function call(method, ...args) {
+  try {
+    return runtime().call(method, ...args);
+  } catch (err) {
+    return Promise.reject(err);
+  }
+}
+function on(name, listener) {
+  return runtime().on(name, listener);
+}
+function once(name, listener) {
+  return runtime().once(name, listener);
+}
+function event(name) {
+  return {
+    name,
+    on: (listener) => on(name, listener),
+    once: (listener) => once(name, listener)
+  };
+}
+function isCallError(err) {
+  return err instanceof Error && err.name === "CallError";
+}
+function onFileDrop(listener) {
+  return on("mygo:file-drop", listener);
+}
+var currentWindow = {
+  minimize: async () => runtime().window.minimize(),
+  maximize: async () => runtime().window.maximize(),
+  unmaximize: async () => runtime().window.unmaximize(),
+  toggleMaximize: async () => runtime().window.toggleMaximize(),
+  isMaximized: async () => runtime().window.isMaximized(),
+  toggleFullScreen: async () => runtime().window.toggleFullScreen(),
+  close: async () => runtime().window.close(),
+  setTitle: async (title) => runtime().window.setTitle(title)
+};
+export {
+  call,
+  currentWindow,
+  event,
+  isCallError,
+  isMyGo,
+  on,
+  onFileDrop,
+  once,
+  runtime
+};

package/dist/types.d.ts

@@ -0,0 +1,30 @@
+/** The operating system, using Node.js' `process.platform` names. */
+export type Platform = "darwin" | "linux" | "win32";
+/** Controls for the window hosting the page, handy for custom title bars. */
+export interface WindowControls {
+    minimize(): Promise<void>;
+    maximize(): Promise<void>;
+    unmaximize(): Promise<void>;
+    toggleMaximize(): Promise<void>;
+    isMaximized(): Promise<boolean>;
+    toggleFullScreen(): Promise<void>;
+    close(): Promise<void>;
+    setTitle(title: string): Promise<void>;
+}
+/** The runtime MyGo injects into every page as `window.mygo`. */
+export interface Runtime {
+    /** Calls a bound Go method, e.g. `call("Greeter.Greet", "Ada")`. */
+    call<T = unknown>(method: string, ...args: unknown[]): Promise<T>;
+    /** Subscribes to a Go event. Returns a function that unsubscribes. */
+    on<T = unknown>(event: string, listener: (payload: T) => void): () => void;
+    /** Like `on`, but unsubscribes after the first event. */
+    once<T = unknown>(event: string, listener: (payload: T) => void): () => void;
+    /** The operating system. */
+    readonly platform: Platform;
+    /** Id of the Go `*mygo.Window` hosting this page. */
+    readonly windowId: number;
+    /** MyGo version. */
+    readonly version: string;
+    /** The window hosting this page. */
+    readonly window: WindowControls;
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "mygo-runtime",
+  "version": "0.1.0",
+  "description": "Typed access to the MyGo runtime in the pages of MyGo desktop apps",
+  "keywords": [
+    "mygo",
+    "desktop",
+    "webview",
+    "go"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/egoist/mygo.git",
+    "directory": "packages/runtime"
+  },
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "bun run build.ts",
+    "test": "bun test"
+  }
+}