@sublime-ui/desktop 0.1.0

package/src/services/fs.ts

@@ -0,0 +1,32 @@
+import { readFile, writeFile, readdir, mkdir as mkdirFs, rm, access } from 'node:fs/promises';
+import { defineNative } from '../define-native';
+
+/**
+ * Built-in `fs` native service.
+ *
+ * A thin, async wrapper over `node:fs/promises` exposed through the native
+ * bridge. Text files are read/written as UTF-8 strings; `mkdir` is recursive
+ * and `remove` maps to `rm` with `recursive` + `force` so it never throws on
+ * a missing path.
+ */
+export const fs = defineNative('fs', {
+  readFile: (path: string): Promise<string> => readFile(path, 'utf8'),
+  writeFile: async (path: string, data: string): Promise<void> => {
+    await writeFile(path, data, 'utf8');
+  },
+  exists: async (path: string): Promise<boolean> => {
+    try {
+      await access(path);
+      return true;
+    } catch {
+      return false;
+    }
+  },
+  readDir: (path: string): Promise<string[]> => readdir(path),
+  mkdir: async (path: string): Promise<void> => {
+    await mkdirFs(path, { recursive: true });
+  },
+  remove: async (path: string): Promise<void> => {
+    await rm(path, { recursive: true, force: true });
+  },
+});

package/src/services/get-electron.ts

@@ -0,0 +1,14 @@
+import type * as Electron from 'electron';
+
+/**
+ * Lazy, mockable accessor for the `electron` runtime module.
+ *
+ * The built-in native services run in the main process, where importing
+ * `electron` is permitted. Going through this single indirection keeps the
+ * import out of module-evaluation time (so the package can be loaded in
+ * environments without Electron) and gives unit tests one seam to mock via
+ * `vi.mock('electron', …)`.
+ */
+export async function getElectron(): Promise<typeof Electron> {
+  return import('electron');
+}

package/src/services/index.ts

@@ -0,0 +1,13 @@
+/**
+ * Built-in native services barrel.
+ *
+ * Re-exports the five batteries-included services authored with
+ * `defineNative` in the main process. Register the ones an app needs via
+ * `registerNative([...])`, then consume them in the renderer with `useNative`.
+ */
+
+export { fs } from './fs';
+export { dialog } from './dialog';
+export { shell } from './shell';
+export { clipboard } from './clipboard';
+export { notifications, type NotifyOptions } from './notifications';

package/src/services/notifications.ts

@@ -0,0 +1,24 @@
+import { defineNative } from '../define-native';
+import { getElectron } from './get-electron';
+
+/** Options for {@link notifications}'s `notify` method. */
+export interface NotifyOptions {
+  /** Title line of the notification. */
+  title: string;
+  /** Body text of the notification. */
+  body: string;
+}
+
+/**
+ * Built-in `notifications` native service.
+ *
+ * Constructs and shows a native OS notification via Electron's `Notification`
+ * class. The Electron module is resolved lazily so the package loads without
+ * Electron and unit tests can mock it.
+ */
+export const notifications = defineNative('notifications', {
+  notify: async ({ title, body }: NotifyOptions): Promise<void> => {
+    const { Notification } = await getElectron();
+    new Notification({ title, body }).show();
+  },
+});

package/src/services/shell.ts

@@ -0,0 +1,24 @@
+import { defineNative } from '../define-native';
+import { getElectron } from './get-electron';
+
+/**
+ * Built-in `shell` native service.
+ *
+ * Thin async wrappers over Electron's `shell` module for opening URLs, paths,
+ * and revealing items in the OS file manager. The Electron module is resolved
+ * lazily so the package loads without Electron and unit tests can mock it.
+ */
+export const shell = defineNative('shell', {
+  openExternal: async (url: string): Promise<void> => {
+    const { shell: s } = await getElectron();
+    await s.openExternal(url);
+  },
+  openPath: async (path: string): Promise<void> => {
+    const { shell: s } = await getElectron();
+    await s.openPath(path);
+  },
+  showItemInFolder: async (path: string): Promise<void> => {
+    const { shell: s } = await getElectron();
+    s.showItemInFolder(path);
+  },
+});

package/src/shell/create-window.ts

@@ -0,0 +1,75 @@
+/**
+ * Secure `BrowserWindow` factory.
+ *
+ * Constructs an Electron window with the hardened defaults the bridge relies
+ * on — `contextIsolation: true`, `nodeIntegration: false`, and the given
+ * preload — so the renderer can only reach native functionality through the
+ * registry-validated `native:invoke` router. The `BrowserWindow` constructor
+ * is injectable so unit tests can assert the wiring without launching Electron;
+ * in production the real constructor is resolved from the `electron` runtime
+ * (this runs in the main process, where requiring `electron` is permitted).
+ *
+ * `entry` is loaded via `loadURL` when it is an `http(s)` URL (dev server) and
+ * via `loadFile` otherwise (packaged HTML on disk).
+ */
+
+import { createRequire } from 'node:module';
+import type { BrowserWindow } from 'electron';
+
+/** Minimal `BrowserWindow` surface the factory drives. */
+export interface BrowserWindowLike {
+  loadURL(url: string): unknown;
+  loadFile(file: string): unknown;
+}
+
+/** Constructor signature for an injectable `BrowserWindow`. */
+export type BrowserWindowCtor = new (opts: {
+  webPreferences: {
+    contextIsolation: boolean;
+    nodeIntegration: boolean;
+    preload: string;
+  };
+}) => BrowserWindow;
+
+/** Options for {@link createWindow}. */
+export interface CreateWindowOptions {
+  /** URL (dev server) or file path (packaged) to load. */
+  entry: string;
+  /** Absolute path to the preload script. */
+  preload: string;
+  /** Injectable `BrowserWindow` constructor; defaults to Electron's. */
+  BrowserWindowCtor?: BrowserWindowCtor;
+}
+
+function resolveCtor(): BrowserWindowCtor {
+  const require = createRequire(import.meta.url);
+  const electron = require('electron') as { BrowserWindow: BrowserWindowCtor };
+  return electron.BrowserWindow;
+}
+
+function isUrl(entry: string): boolean {
+  return /^https?:\/\//.test(entry);
+}
+
+/**
+ * Construct a hardened `BrowserWindow` and load `entry`.
+ *
+ * @param opts Window options; `BrowserWindowCtor` is injectable for tests.
+ * @returns The constructed window.
+ */
+export function createWindow(opts: CreateWindowOptions): BrowserWindow {
+  const Ctor = opts.BrowserWindowCtor ?? resolveCtor();
+  const win = new Ctor({
+    webPreferences: {
+      contextIsolation: true,
+      nodeIntegration: false,
+      preload: opts.preload,
+    },
+  });
+  if (isUrl(opts.entry)) {
+    win.loadURL(opts.entry);
+  } else {
+    win.loadFile(opts.entry);
+  }
+  return win;
+}

package/src/shell/main.ts

@@ -0,0 +1,70 @@
+/**
+ * Electron application entry for the native bridge.
+ *
+ * `startDesktop` is the single bootstrap the packaged main process calls: once
+ * Electron's `app` reports ready it installs the `native:invoke` router onto
+ * `ipcMain` and opens the hardened {@link createWindow}. `app` and `ipcMain`
+ * are injected so unit tests can drive the flow with fakes (an
+ * immediately-resolving `whenReady`, a recording `ipcMain`) without launching
+ * Electron. `isDev` selects how the entry is loaded — a dev server URL via
+ * `loadURL` versus packaged HTML on disk via `loadFile`, which `createWindow`
+ * derives from the `entry` shape.
+ */
+
+import { createWindow, type BrowserWindowCtor } from './create-window';
+import { installNativeRouter, type IpcMainLike } from '../bridge/main-router';
+
+/** Minimal Electron `app` surface needed to bootstrap. Injectable. */
+export interface AppLike {
+  whenReady(): Promise<unknown>;
+}
+
+/** Options for {@link startDesktop}. */
+export interface StartDesktopOptions {
+  /** Electron's `app` (or a compatible fake for tests). */
+  app: AppLike;
+  /** Electron's `ipcMain` (or a compatible fake for tests). */
+  ipcMain: IpcMainLike;
+  /** URL (dev) or file path (packaged) to load in the window. */
+  entry: string;
+  /** Absolute path to the preload script. */
+  preload: string;
+  /** Whether running against a dev server. */
+  isDev: boolean;
+  /** Injectable `BrowserWindow` constructor; defaults to Electron's. */
+  BrowserWindowCtor?: BrowserWindowCtor;
+  /**
+   * Called if `whenReady` rejects or window creation throws. Defaults to
+   * logging the error, so a failed bootstrap never becomes an unhandled
+   * promise rejection.
+   */
+  onError?: (error: unknown) => void;
+}
+
+/**
+ * Bootstrap the desktop shell: install the native router and open the window
+ * once the app is ready.
+ *
+ * @param opts Bootstrap options; `app`/`ipcMain`/`BrowserWindowCtor` are
+ *   injectable for tests.
+ */
+export function startDesktop(opts: StartDesktopOptions): void {
+  const onError =
+    opts.onError ??
+    ((error: unknown): void => {
+      console.error('[sublime/desktop] startDesktop failed:', error);
+    });
+  void opts.app
+    .whenReady()
+    .then(() => {
+      installNativeRouter(opts.ipcMain);
+      createWindow({
+        entry: opts.entry,
+        preload: opts.preload,
+        ...(opts.BrowserWindowCtor !== undefined
+          ? { BrowserWindowCtor: opts.BrowserWindowCtor }
+          : {}),
+      });
+    })
+    .catch(onError);
+}

package/src/types.ts

@@ -0,0 +1,16 @@
+/**
+ * Core contract types for native services.
+ *
+ * A native service is a named bag of async methods authored in the main
+ * process. Methods are always async because every call crosses the
+ * `native:invoke` IPC boundary.
+ */
+
+/** A map of async native methods keyed by method name. */
+export type NativeMethods = Record<string, (...args: any[]) => Promise<any>>;
+
+/** A named native service: its `name` plus its async `methods`. */
+export interface NativeService<M extends NativeMethods = NativeMethods> {
+  name: string;
+  methods: M;
+}

package/src/use-native.ts

@@ -0,0 +1,57 @@
+/**
+ * Renderer hook for consuming a native service from React.
+ *
+ * `useNative('fs')` reads the `window.sublimeNative` bridge exposed by the
+ * preload (see `exposeNativeBridge`). On plain web — where no preload ran and
+ * the bridge is absent — it returns `null`, letting components gracefully
+ * degrade. Inside the Electron shell it returns a typed {@link createProxy}
+ * whose `invoke` forwards over the one `native:invoke` channel and revives any
+ * `{ __nativeError }` envelope (produced by the main router) back into a
+ * {@link NativeError} so the caller sees a normal rejected promise.
+ */
+
+import { createProxy } from './bridge/proxy';
+import { deserializeError } from './errors';
+import type { SerializedError } from './errors';
+import type { NativeMethods } from './types';
+
+/** Shape of the bridge exposed at `window.sublimeNative` by the preload. */
+interface SublimeNativeWindow {
+  invoke(mod: string, method: string, args: unknown[]): Promise<unknown>;
+}
+
+/** Envelope shape returned by the main router when a native call fails. */
+interface NativeErrorEnvelope {
+  __nativeError: SerializedError;
+}
+
+function isNativeErrorEnvelope(value: unknown): value is NativeErrorEnvelope {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    '__nativeError' in value
+  );
+}
+
+/**
+ * Access a native service by name from the renderer.
+ *
+ * @typeParam M the service's method map (from the `defineNative` author).
+ * @param name  the registry key of the native service (e.g. `'fs'`).
+ * @returns a typed proxy, or `null` when running outside the Electron shell.
+ */
+export function useNative<M extends NativeMethods>(name: string): M | null {
+  const bridge = (
+    globalThis as { sublimeNative?: SublimeNativeWindow }
+  ).sublimeNative;
+  if (bridge === undefined) {
+    return null;
+  }
+  return createProxy<M>(name, async (mod, method, args) => {
+    const result = await bridge.invoke(mod, method, args);
+    if (isNativeErrorEnvelope(result)) {
+      throw deserializeError(result.__nativeError);
+    }
+    return result;
+  });
+}