@timmo001/groundwork-desktop 0.0.0-stage → 0.27.0

package/src/main.ts

@@ -0,0 +1,613 @@
+/**
+ * The main process half of `@timmo001/groundwork-desktop`: opens an app's
+ * window with the browser defaults its `desktop.config` leaves on, such as
+ * the tray, remembered size and zoom, one instance only, external links in
+ * the system browser and the requests the view part makes. With `runInTray`
+ * the app keeps running in the tray once the window closes.
+ *
+ * It takes the app's own Electrobun, so the app keeps its pinned release:
+ *
+ *   import Electrobun, { BrowserView } from "electrobun/main";
+ *   await openDesktopWindow(Electrobun, { title, url, frame, config, createRPC });
+ */
+import { join } from "node:path";
+
+import { Option, Schema } from "effect";
+
+import {
+  readOmarchyTheme,
+  watchOmarchyTheme,
+} from "@timmo001/groundwork-tokens/omarchy-current";
+
+import {
+  isExternal,
+  resolveConfig,
+  type DesktopConfig,
+  type ResolvedDesktopConfig,
+} from "./config.ts";
+import { hiddenVariable, loginItem } from "./login.ts";
+import type { DesktopRequests, Notice, OmarchyThemeMessage } from "./rpc.ts";
+
+export * from "./config.ts";
+
+export { hiddenVariable } from "./login.ts";
+
+export type * from "./rpc.ts";
+
+interface Frame {
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+}
+
+/** A webview event: the URL, or for links and downloads what the webview sent. */
+interface WebviewEvent {
+  readonly data: {
+    readonly detail: string | { readonly url?: string; readonly path?: string };
+  };
+}
+
+interface MainView {
+  readonly id: number;
+  setPageZoom(zoom: number): void;
+  findInPage(text: string, options?: { forward?: boolean }): void;
+  stopFindInPage(): void;
+  toggleDevTools(): void;
+  setNavigationRules(rules: string[]): void;
+}
+
+interface MainWindow {
+  readonly webview: MainView;
+  on(name: "resize" | "move" | "close", handler: () => void): void;
+  getFrame(): Frame;
+  show(): void;
+  activate(): void;
+  unminimize(): void;
+}
+
+interface MainRPC {
+  readonly send: {
+    notice(notice: Notice): void;
+    deepLink(link: { url: string }): void;
+    omarchyTheme(message: OmarchyThemeMessage): void;
+  };
+}
+
+/**
+ * An item in the tray's menu: a divider, or a label with the action
+ * `onTrayAction` hears. `enabled: false` greys it out, such as for a status
+ * line, and `checked` ticks it.
+ */
+export type TrayItem =
+  | { readonly type: "divider" }
+  | {
+      readonly type: "normal";
+      readonly label: string;
+      readonly action?: string;
+      readonly enabled?: boolean;
+      readonly checked?: boolean;
+    };
+
+interface MainTray {
+  readonly id: number;
+  setMenu(menu: TrayItem[]): void;
+}
+
+/** The parts of Electrobun's main process this uses, with the app's RPC type. */
+export interface ElectrobunMain<RPC extends MainRPC> {
+  readonly BrowserWindow: new (options: {
+    title: string;
+    url: string;
+    frame: { x?: number; y?: number; width: number; height: number };
+    rpc: RPC;
+    spellCheck: boolean;
+    preload: string | null;
+  }) => MainWindow;
+  readonly Tray: new (options: {
+    title?: string;
+    image?: string;
+    template?: boolean;
+    width?: number;
+    height?: number;
+  }) => MainTray;
+  readonly Utils: {
+    openExternal(url: string): boolean;
+    clipboardReadText(): string | null;
+    clipboardWriteText(text: string): void;
+    showNotification(options: { title: string; body?: string }): void;
+    quit(code?: number): boolean;
+    readonly paths: { readonly userData: string };
+  };
+  readonly BuildConfig: { getSync(): { channel: string } };
+  readonly events: {
+    on(
+      name: "open-url",
+      handler: (event: { readonly data: { readonly url: string } }) => void,
+    ): void;
+    /** Webview events, per webview id; Electrobun's typed `webview.on` passes `unknown`. */
+    on(
+      name: `${"dom-ready" | "will-navigate" | "download-completed" | "new-window-open"}-${number}`,
+      handler: (event: WebviewEvent) => void,
+    ): void;
+    /** Tray clicks, per tray id. */
+    on(
+      name: `tray-clicked-${number}`,
+      handler: (event: { readonly data: { readonly action: string } }) => void,
+    ): void;
+  };
+}
+
+/** What `openDesktopWindow` opens. */
+export interface DesktopWindowOptions<RPC extends MainRPC> {
+  readonly title: string;
+  /**
+   * The page, such as `views://mainview/index.html`, or one from an origin in
+   * the config's `ownOrigins`.
+   */
+  readonly url: string;
+  /** The first size and place, before one is remembered. */
+  readonly frame: {
+    readonly width: number;
+    readonly height: number;
+    readonly x?: number;
+    readonly y?: number;
+  };
+  readonly config?: DesktopConfig;
+  /**
+   * Defines the window's RPC from the desktop requests, beside the app's own:
+   *
+   *   (requests: DesktopRequests) => BrowserView.defineRPC<DesktopSchema<AppRequests>>({
+   *     handlers: { requests: { ...requests, ...appRequests } },
+   *   })
+   *
+   * Type `requests` as here, so the window takes the RPC's own type.
+   */
+  readonly createRPC: (requests: DesktopRequests) => RPC;
+  /**
+   * JavaScript run in every page before the page's own, such as a built
+   * script that calls `connectDesktop`, for a page served from elsewhere.
+   * The script's text, not its address: Linux takes no `views://` address.
+   */
+  readonly preload?: string;
+  /**
+   * Runs once this copy is the only one, before the window first opens, such
+   * as to start the server the page comes from.
+   */
+  readonly ready?: () => Promise<void>;
+  /** The app's own tray items, between the show item and the rest. */
+  readonly trayItems?: readonly TrayItem[];
+  /** Called with the action of each of the app's own tray items picked. */
+  readonly onTrayAction?: (action: string) => void;
+}
+
+/** The app's window and tray, and a way to show a notice in the window. */
+export interface DesktopWindow<RPC extends MainRPC> {
+  /** The window open now; with `runInTray`, none while it's closed. */
+  readonly window: MainWindow | undefined;
+  readonly rpc: RPC;
+  readonly config: ResolvedDesktopConfig;
+  /** A system notification when the config turns them on, otherwise in the app. */
+  readonly notify: (notice: Notice) => void;
+  /** Opens the window, or brings it to the front. */
+  readonly show: () => void;
+  /** Replaces the app's own tray items, such as a status line that changed. */
+  readonly setTrayItems: (items: readonly TrayItem[]) => void;
+}
+
+interface SavedState {
+  frame?: Frame;
+  zoom?: number;
+}
+
+/** The state file as written, before it's checked. */
+interface SavedFile {
+  readonly frame?: Partial<Frame>;
+  readonly zoom?: number;
+}
+
+const zoomSteps = [0.5, 0.67, 0.75, 0.8, 0.9, 1, 1.1, 1.25, 1.5, 1.75, 2];
+
+const decodeNavigation = Schema.decodeUnknownOption(
+  Schema.fromJsonString(Schema.Struct({ url: Schema.String })),
+);
+
+// Navigation events send their detail as JSON text, `{"url", "allowed"}`;
+// others send the URL itself or an object
+const detailUrl = ({ data }: WebviewEvent): string | undefined => {
+  const { detail } = data;
+
+  if (detail instanceof Object) return detail.url;
+
+  return detail.startsWith("{")
+    ? Option.getOrUndefined(
+        Option.map(decodeNavigation(detail), ({ url }) => url),
+      )
+    : detail;
+};
+
+// GTK 3 only takes whole numbers in GDK_SCALE and drops the fraction, so on
+// Linux the page zoom makes up the rest: 1.6 renders at 1 and zooms by 1.6
+const toolkitZoom = (): number => {
+  const scale = Number(process.env.GDK_SCALE);
+
+  return process.platform === "linux" && scale > 0
+    ? scale / Math.max(1, Math.floor(scale))
+    : 1;
+};
+
+// Electrobun runs GTK on X11, where nothing hands GTK the system's color
+// scheme, so WebKitGTK reports light to `prefers-color-scheme`. WebKitGTK also
+// takes a `:dark` GTK_THEME as dark, so set one from the desktop portal's
+// scheme, unless the user set GTK_THEME themselves. It goes through libc's
+// setenv, since Bun's `process.env` doesn't reach the native side
+const followSystemScheme = async () => {
+  if (process.platform !== "linux" || process.env.GTK_THEME !== undefined)
+    return;
+
+  try {
+    const result = Bun.spawnSync([
+      "gdbus",
+      "call",
+      "--session",
+      "--dest=org.freedesktop.portal.Desktop",
+      "--object-path=/org/freedesktop/portal/desktop",
+      "--method=org.freedesktop.portal.Settings.ReadOne",
+      "org.freedesktop.appearance",
+      "color-scheme",
+    ]);
+
+    // 1 is prefer dark; 0 (no preference) and 2 (prefer light) stay light
+    if (!(result.success && /\buint32 1\b/.test(result.stdout.toString())))
+      return;
+
+    const { dlopen, FFIType } = await import("bun:ffi");
+
+    const { symbols } = dlopen("libc.so.6", {
+      setenv: {
+        args: [FFIType.cstring, FFIType.cstring, FFIType.i32],
+        returns: FFIType.i32,
+      },
+    });
+
+    symbols.setenv(
+      Buffer.from("GTK_THEME\0"),
+      Buffer.from("Adwaita:dark\0"),
+      0,
+    );
+  } catch {
+    // No gdbus or no portal: the webview keeps GTK's own scheme
+  }
+};
+
+const toFrame = (frame: Partial<Frame> = {}): Frame | undefined => {
+  const { x, y, width, height } = frame;
+
+  if (
+    x === undefined ||
+    y === undefined ||
+    width === undefined ||
+    height === undefined
+  )
+    return undefined;
+
+  return [x, y, width, height].every(Number.isFinite) && width > 0 && height > 0
+    ? { x, y, width, height }
+    : undefined;
+};
+
+const readState = async (path: string): Promise<SavedState> => {
+  const state: SavedState = {};
+
+  try {
+    const saved: SavedFile = await Bun.file(path).json();
+    const frame = toFrame(saved.frame);
+
+    if (frame !== undefined) state.frame = frame;
+
+    if (saved.zoom !== undefined && zoomSteps.includes(saved.zoom))
+      state.zoom = saved.zoom;
+  } catch {
+    // No state yet, or a broken file: the app opens as if new
+  }
+
+  return state;
+};
+
+// The first copy listens on a socket in the app's data folder. A second one
+// finds it there, asks it to come to the front and quits.
+const claimInstance = async (
+  socket: string,
+  onShow: () => void,
+): Promise<boolean> => {
+  try {
+    const other = await Bun.connect({ unix: socket, socket: { data() {} } });
+
+    other.write("show");
+    other.end();
+
+    return false;
+  } catch {
+    await Bun.file(socket)
+      .delete()
+      .catch(() => undefined);
+  }
+
+  try {
+    Bun.listen({ unix: socket, socket: { data: onShow } });
+  } catch {
+    // Without a socket each copy runs on its own
+  }
+
+  return true;
+};
+
+/** Opens the app's window with the defaults its config leaves on. */
+export const openDesktopWindow = async <RPC extends MainRPC>(
+  electrobun: ElectrobunMain<NoInfer<RPC>>,
+  options: DesktopWindowOptions<RPC>,
+): Promise<DesktopWindow<RPC>> => {
+  const { Utils } = electrobun;
+  const config = resolveConfig(options.config);
+  const dev = electrobun.BuildConfig.getSync().channel === "dev";
+  const statePath = join(Utils.paths.userData, "desktop-state.json");
+
+  const state =
+    config.windowState || config.zoomKeys ? await readState(statePath) : {};
+
+  let window: MainWindow | undefined;
+  // Set once the window can open; a second copy asking before then just waits
+  let show = () => {};
+
+  if (
+    config.singleInstance &&
+    !(await claimInstance(join(Utils.paths.userData, "instance.sock"), () =>
+      show(),
+    ))
+  ) {
+    Utils.quit(0);
+
+    return new Promise(() => {});
+  }
+
+  const baseZoom =
+    toolkitZoom() *
+    (Number(process.env.GROUNDWORK_DESKTOP_ZOOM) || 1) *
+    config.zoom;
+
+  let zoom = config.zoomKeys ? (state.zoom ?? 1) : 1;
+  let saveTimer: ReturnType<typeof setTimeout> | undefined;
+
+  const save = () => {
+    clearTimeout(saveTimer);
+    saveTimer = setTimeout(() => {
+      const next: SavedState = {};
+
+      if (config.windowState && window !== undefined) {
+        next.frame = window.getFrame();
+        // A window opened again from the tray opens where this one was
+        state.frame = next.frame;
+      }
+
+      if (config.zoomKeys) next.zoom = zoom;
+      void Bun.write(statePath, JSON.stringify(next));
+    }, 500);
+  };
+
+  const desktopRequests: DesktopRequests = {
+    config: () => ({ config, dev }),
+    openExternal: ({ url }) =>
+      config.externalLinks &&
+      isExternal(url, config) &&
+      Utils.openExternal(url),
+    clipboardRead: () =>
+      config.clipboard ? (Utils.clipboardReadText() ?? "") : "",
+    clipboardWrite: ({ text }) => {
+      if (!config.clipboard) return false;
+      Utils.clipboardWriteText(text);
+
+      return true;
+    },
+    find: ({ text, forward }) => {
+      if (!config.find) return false;
+      window?.webview.findInPage(text, { forward });
+
+      return true;
+    },
+    stopFind: () => {
+      window?.webview.stopFindInPage();
+
+      return true;
+    },
+    zoom: ({ step }) => {
+      if (!config.zoomKeys) return zoom;
+      const index = zoomSteps.indexOf(zoom);
+
+      const next = Math.min(
+        zoomSteps.length - 1,
+        Math.max(0, index + (step === "in" ? 1 : -1)),
+      );
+
+      zoom = step === "reset" ? 1 : (zoomSteps[next] ?? 1);
+      window?.webview.setPageZoom(baseZoom * zoom);
+      save();
+
+      return zoom;
+    },
+    devTools: () => {
+      if (!(config.devTools && dev)) return false;
+      window?.webview.toggleDevTools();
+
+      return true;
+    },
+    notify: ({ heading, body }) => {
+      if (!config.notifications) return false;
+      Utils.showNotification(
+        body === undefined ? { title: heading } : { title: heading, body },
+      );
+
+      return true;
+    },
+    omarchyTheme: async () => ({
+      theme: config.omarchyTheme ? await readOmarchyTheme() : null,
+    }),
+  };
+
+  const rpc = options.createRPC(desktopRequests);
+
+  const notify = (notice: Notice) => {
+    if (!desktopRequests.notify(notice)) rpc.send.notice(notice);
+  };
+
+  // The rules and listeners go on each window's webview, since a window
+  // opened again from the tray has a new one
+  const openWindow = () => {
+    const opened = new electrobun.BrowserWindow({
+      title: options.title,
+      url: options.url,
+      frame: (config.windowState ? state.frame : undefined) ?? options.frame,
+      rpc,
+      spellCheck: config.spellcheck,
+      preload: options.preload ?? null,
+    });
+
+    const applyZoom = () => opened.webview.setPageZoom(baseZoom * zoom);
+    const id = opened.webview.id;
+
+    window = opened;
+    applyZoom();
+    electrobun.events.on(`dom-ready-${id}`, applyZoom);
+    opened.on("close", () => {
+      if (window === opened) window = undefined;
+    });
+
+    if (config.windowState) {
+      opened.on("resize", save);
+      opened.on("move", save);
+    }
+
+    if (config.externalLinks) {
+      const openOutside = (event: WebviewEvent) => {
+        const url = detailUrl(event);
+
+        if (url !== undefined && isExternal(url, config))
+          Utils.openExternal(url);
+      };
+
+      // Only the app's own pages load in the window; links out go to the browser
+      opened.webview.setNavigationRules([
+        "^*",
+        "views://*",
+        ...config.ownOrigins.map((origin) => `${new URL(origin).origin}/*`),
+      ]);
+      electrobun.events.on(`will-navigate-${id}`, openOutside);
+      electrobun.events.on(`new-window-open-${id}`, openOutside);
+    }
+
+    if (config.downloads) {
+      electrobun.events.on(`download-completed-${id}`, ({ data }) => {
+        const path =
+          data.detail instanceof Object ? data.detail.path : data.detail;
+
+        const heading = config.labels.downloadFinished;
+
+        notify(
+          path === undefined || path === ""
+            ? { heading, tone: "success" }
+            : { heading, body: path, tone: "success" },
+        );
+      });
+    }
+  };
+
+  show = () => {
+    if (window === undefined) return openWindow();
+    window.unminimize();
+    window.show();
+    window.activate();
+  };
+
+  await options.ready?.();
+  await followSystemScheme();
+
+  if (!(config.runInTray && process.env[hiddenVariable] === "1")) openWindow();
+
+  if (config.deepLinks) {
+    electrobun.events.on("open-url", ({ data }) => {
+      show();
+      rpc.send.deepLink({ url: data.url });
+    });
+  }
+
+  if (config.omarchyTheme) {
+    watchOmarchyTheme((theme) => rpc.send.omarchyTheme({ theme }));
+  }
+
+  let setTrayItems = (_items: readonly TrayItem[]) => {};
+
+  if (config.tray !== false) {
+    const tray = new electrobun.Tray({
+      title: config.tray.title,
+      image: config.tray.image,
+      template: false,
+      width: 22,
+      height: 22,
+    });
+
+    const login = config.startAtLogin ? await loginItem() : undefined;
+    let atLogin = (await login?.enabled()) ?? false;
+    let appItems = options.trayItems ?? [];
+
+    const setMenu = () =>
+      tray.setMenu([
+        {
+          type: "normal",
+          label: config.labels.show ?? `Show ${options.title}`,
+          action: "show",
+        },
+        ...(appItems.length > 0
+          ? [{ type: "divider" } as const, ...appItems]
+          : []),
+        { type: "divider" },
+        ...(login === undefined
+          ? []
+          : [
+              {
+                type: "normal",
+                label: config.labels.startAtLogin,
+                action: "start-at-login",
+                checked: atLogin,
+              } as const,
+            ]),
+        { type: "normal", label: config.labels.quit, action: "quit" },
+      ]);
+
+    setTrayItems = (items) => {
+      appItems = items;
+      setMenu();
+    };
+
+    setMenu();
+    electrobun.events.on(`tray-clicked-${tray.id}`, ({ data }) => {
+      if (data.action === "quit") Utils.quit(0);
+      else if (data.action === "show" || data.action === "") show();
+      else if (data.action === "start-at-login" && login !== undefined) {
+        void login.set(!atLogin).then(async () => {
+          atLogin = await login.enabled();
+          setMenu();
+        });
+      } else options.onTrayAction?.(data.action);
+    });
+  }
+
+  return {
+    get window() {
+      return window;
+    },
+    rpc,
+    config,
+    notify,
+    show: () => show(),
+    setTrayItems: (items) => setTrayItems(items),
+  };
+};

package/src/rpc.ts

@@ -0,0 +1,96 @@
+/**
+ * The messages between a desktop app's main process and its view: what the
+ * view asks for, and what the main process tells it. An app adds its own
+ * requests beside these.
+ */
+import type { OmarchyCurrentTheme } from "@timmo001/groundwork-tokens/runtime";
+
+import type { ResolvedDesktopConfig } from "./config.ts";
+
+/** The desktop's Omarchy theme, or `null` where there's none or it's off. */
+export interface OmarchyThemeMessage {
+  readonly theme: OmarchyCurrentTheme | null;
+}
+
+/** A notice for the view to show in the app, such as a finished download. */
+export interface Notice {
+  readonly heading: string;
+  readonly body?: string;
+  readonly tone?: "neutral" | "info" | "success" | "warning" | "danger";
+}
+
+/** What a request may answer with: anything that survives JSON. */
+export type Reply = string | number | boolean | null | void | object;
+
+/** An app's own requests from its view, by name. */
+export type RequestHandlers = Record<
+  string,
+  (params: never) => Reply | Promise<Reply>
+>;
+
+/** What the view asks the main process for. */
+export interface DesktopRequests {
+  /** The resolved config and whether this is a dev build. */
+  readonly config: () => {
+    readonly config: ResolvedDesktopConfig;
+    readonly dev: boolean;
+  };
+  /** Opens a URL in the system browser, when the config allows its scheme. */
+  readonly openExternal: (params: { readonly url: string }) => boolean;
+  readonly clipboardRead: () => string;
+  readonly clipboardWrite: (params: { readonly text: string }) => boolean;
+  /** Finds text in the page, or the next match. */
+  readonly find: (params: {
+    readonly text: string;
+    readonly forward: boolean;
+  }) => boolean;
+  readonly stopFind: () => boolean;
+  /** Steps the remembered zoom in or out, or back to 1. */
+  readonly zoom: (params: { readonly step: "in" | "out" | "reset" }) => number;
+  /** Opens or closes the dev tools, in dev builds only. */
+  readonly devTools: () => boolean;
+  /** A system notification when the config turns them on, otherwise false. */
+  readonly notify: (params: Notice) => boolean;
+  /** The desktop's Omarchy theme, when the config passes it on. */
+  readonly omarchyTheme: () => Promise<OmarchyThemeMessage>;
+}
+
+/** What the main process tells the view. */
+export interface DesktopMessages {
+  readonly notice: Notice;
+  /** A deep link the app was opened with. */
+  readonly deepLink: { readonly url: string };
+  /** The desktop switched its Omarchy theme. */
+  readonly omarchyTheme: OmarchyThemeMessage;
+}
+
+/** Requests in the `{ params, response }` shape Electrobun's schemas use. */
+export type RequestSchemas<R> = {
+  [K in keyof R]: R[K] extends () => infer T
+    ? { params: undefined; response: Awaited<T> }
+    : R[K] extends (params: infer P) => infer T
+      ? { params: P; response: Awaited<T> }
+      : never;
+};
+
+/**
+ * The app's Electrobun RPC schema: the desktop requests and the app's own,
+ * and the desktop messages. Pass it to `defineRPC` on both sides:
+ *
+ *   BrowserView.defineRPC<DesktopSchema<AppRequests>>(...)
+ *   Electroview.defineRPC<DesktopSchema<AppRequests>>(...)
+ */
+export type DesktopSchema<AppRequests extends RequestHandlers = {}> = {
+  bun: {
+    requests: RequestSchemas<DesktopRequests & AppRequests>;
+    messages: {};
+  };
+  webview: { requests: {}; messages: DesktopMessages };
+};
+
+/** The view's handlers for the desktop messages, for `Electroview.defineRPC`. */
+export interface DesktopMessageHandlers {
+  readonly notice: (notice: Notice) => void;
+  readonly deepLink: (link: { readonly url: string }) => void;
+  readonly omarchyTheme: (message: OmarchyThemeMessage) => void;
+}