@sublime-ui/desktop 0.1.0

package/dist/services/shell.js

@@ -0,0 +1,19 @@
+import { defineNative } from "../define-native";
+import { getElectron } from "./get-electron";
+const shell = defineNative("shell", {
+  openExternal: async (url) => {
+    const { shell: s } = await getElectron();
+    await s.openExternal(url);
+  },
+  openPath: async (path) => {
+    const { shell: s } = await getElectron();
+    await s.openPath(path);
+  },
+  showItemInFolder: async (path) => {
+    const { shell: s } = await getElectron();
+    s.showItemInFolder(path);
+  }
+});
+export {
+  shell
+};

package/dist/shell/create-window.d.ts

@@ -0,0 +1,48 @@
+import { BrowserWindow } from 'electron';
+
+/**
+ * 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).
+ */
+
+/** Minimal `BrowserWindow` surface the factory drives. */
+interface BrowserWindowLike {
+    loadURL(url: string): unknown;
+    loadFile(file: string): unknown;
+}
+/** Constructor signature for an injectable `BrowserWindow`. */
+type BrowserWindowCtor = new (opts: {
+    webPreferences: {
+        contextIsolation: boolean;
+        nodeIntegration: boolean;
+        preload: string;
+    };
+}) => BrowserWindow;
+/** Options for {@link createWindow}. */
+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;
+}
+/**
+ * Construct a hardened `BrowserWindow` and load `entry`.
+ *
+ * @param opts Window options; `BrowserWindowCtor` is injectable for tests.
+ * @returns The constructed window.
+ */
+declare function createWindow(opts: CreateWindowOptions): BrowserWindow;
+
+export { type BrowserWindowCtor, type BrowserWindowLike, type CreateWindowOptions, createWindow };

package/dist/shell/create-window.js

@@ -0,0 +1,28 @@
+import { createRequire } from "node:module";
+function resolveCtor() {
+  const require2 = createRequire(import.meta.url);
+  const electron = require2("electron");
+  return electron.BrowserWindow;
+}
+function isUrl(entry) {
+  return /^https?:\/\//.test(entry);
+}
+function createWindow(opts) {
+  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;
+}
+export {
+  createWindow
+};

package/dist/shell/main.d.ts

@@ -0,0 +1,53 @@
+import { BrowserWindowCtor } from './create-window.js';
+import { IpcMainLike } from '../bridge/main-router.js';
+import 'electron';
+import '../errors.js';
+
+/**
+ * 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.
+ */
+
+/** Minimal Electron `app` surface needed to bootstrap. Injectable. */
+interface AppLike {
+    whenReady(): Promise<unknown>;
+}
+/** Options for {@link startDesktop}. */
+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.
+ */
+declare function startDesktop(opts: StartDesktopOptions): void;
+
+export { type AppLike, type StartDesktopOptions, startDesktop };

package/dist/shell/main.js

@@ -0,0 +1,18 @@
+import { createWindow } from "./create-window";
+import { installNativeRouter } from "../bridge/main-router";
+function startDesktop(opts) {
+  const onError = opts.onError ?? ((error) => {
+    console.error("[sublime/desktop] startDesktop failed:", error);
+  });
+  void opts.app.whenReady().then(() => {
+    installNativeRouter(opts.ipcMain);
+    createWindow({
+      entry: opts.entry,
+      preload: opts.preload,
+      ...opts.BrowserWindowCtor !== void 0 ? { BrowserWindowCtor: opts.BrowserWindowCtor } : {}
+    });
+  }).catch(onError);
+}
+export {
+  startDesktop
+};

package/dist/types.d.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. */
+type NativeMethods = Record<string, (...args: any[]) => Promise<any>>;
+/** A named native service: its `name` plus its async `methods`. */
+interface NativeService<M extends NativeMethods = NativeMethods> {
+    name: string;
+    methods: M;
+}
+
+export type { NativeMethods, NativeService };

package/dist/use-native.d.ts

@@ -0,0 +1,24 @@
+import { NativeMethods } from './types.js';
+
+/**
+ * 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.
+ */
+
+/**
+ * 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.
+ */
+declare function useNative<M extends NativeMethods>(name: string): M | null;
+
+export { useNative };

package/dist/use-native.js

@@ -0,0 +1,21 @@
+import { createProxy } from "./bridge/proxy";
+import { deserializeError } from "./errors";
+function isNativeErrorEnvelope(value) {
+  return typeof value === "object" && value !== null && "__nativeError" in value;
+}
+function useNative(name) {
+  const bridge = globalThis.sublimeNative;
+  if (bridge === void 0) {
+    return null;
+  }
+  return createProxy(name, async (mod, method, args) => {
+    const result = await bridge.invoke(mod, method, args);
+    if (isNativeErrorEnvelope(result)) {
+      throw deserializeError(result.__nativeError);
+    }
+    return result;
+  });
+}
+export {
+  useNative
+};

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@sublime-ui/desktop",
+  "version": "0.1.0",
+  "description": "Electron desktop packaging and a secure native bridge (defineNative/useNative over one IPC channel) for Sublime UI apps.",
+  "keywords": ["sublime-ui", "electron", "desktop", "ipc", "native-bridge", "electron-forge", "cross-platform", "typescript"],
+  "homepage": "https://sublime-ui.github.io/sublime-ui/",
+  "bugs": "https://github.com/sublime-ui/sublime-ui/issues",
+  "repository": { "type": "git", "url": "git+https://github.com/sublime-ui/sublime-ui.git", "directory": "desktop" },
+  "license": "MIT",
+  "author": "Aaron Mkandawire",
+  "publishConfig": { "access": "public" },
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" },
+    "./client": { "types": "./dist/client.d.ts", "import": "./dist/client.js" }
+  },
+  "files": ["dist", "src"],
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "lint": "eslint src"
+  },
+  "peerDependencies": { "electron": ">=30", "react": ">=18" },
+  "peerDependenciesMeta": { "electron": { "optional": true }, "react": { "optional": true } },
+  "devDependencies": {
+    "@types/node": "^22",
+    "@types/react": "^18.3.12",
+    "electron": "^33.0.0",
+    "react": "^18.3.1",
+    "@testing-library/react": "^16.0.1",
+    "jsdom": "^25.0.1"
+  }
+}

package/src/bridge/main-router.ts

@@ -0,0 +1,52 @@
+/**
+ * Main-process IPC router for the single `native:invoke` channel.
+ *
+ * Registers one handler that resolves `(module, method)` against the native
+ * registry and dispatches. Unknown pairs throw a {@link NativeError}; any
+ * throw (unknown or from the impl) is caught and returned as a
+ * `{ __nativeError: SerializedError }` envelope, which the renderer proxy
+ * (`useNative` / Task 8) revives into a {@link NativeError} and rethrows.
+ * Keeping the error convention as a returned envelope — rather than a rejected
+ * promise — gives the proxy a single, structured-clone-safe shape to detect.
+ */
+
+import { resolve } from '../registry';
+import { NativeError, serializeError, type SerializedError } from '../errors';
+
+/** Envelope returned over IPC when a native call fails. */
+export interface NativeErrorEnvelope {
+  __nativeError: SerializedError;
+}
+
+/** Minimal `ipcMain` surface needed to register the channel. Injectable. */
+export interface IpcMainLike {
+  handle(channel: string, listener: (e: unknown, ...args: any[]) => any): void;
+}
+
+/**
+ * Install the `native:invoke` router onto the given `ipcMain`.
+ *
+ * @param ipcMain Electron's `ipcMain` (or a compatible fake for tests).
+ */
+export function installNativeRouter(ipcMain: IpcMainLike): void {
+  ipcMain.handle(
+    'native:invoke',
+    async (
+      _event: unknown,
+      mod: string,
+      method: string,
+      args: unknown[] = [],
+    ): Promise<unknown> => {
+      try {
+        const fn = resolve(mod, method);
+        if (fn === undefined) {
+          throw new NativeError(`Unknown native method ${mod}:${method}`);
+        }
+        return await fn(...args);
+      } catch (e) {
+        const envelope: NativeErrorEnvelope = { __nativeError: serializeError(e) };
+        return envelope;
+      }
+    },
+  );
+}

package/src/bridge/preload.ts

@@ -0,0 +1,43 @@
+/**
+ * Preload bridge: exposes the typed native surface to the renderer.
+ *
+ * Runs in Electron's isolated preload context (the only place with access to
+ * `contextBridge`). It exposes a single object, `window.sublimeNative`, whose
+ * `invoke` forwards every call over the one generic `native:invoke` channel to
+ * the main-process router (Task 6). Nothing else is exposed — keeping
+ * `contextIsolation: true` / `nodeIntegration: false` meaningful — so the
+ * renderer can only reach native functionality through the registry-validated
+ * router. `useNative` (Task 8) reads this surface and revives error envelopes.
+ */
+
+/** Minimal `contextBridge` surface needed to expose the bridge. Injectable. */
+export interface ContextBridgeLike {
+  exposeInMainWorld(key: string, api: unknown): void;
+}
+
+/** Minimal `ipcRenderer` surface needed to forward invocations. Injectable. */
+export interface IpcRendererLike {
+  invoke(channel: string, ...args: any[]): Promise<unknown>;
+}
+
+/** Shape exposed at `window.sublimeNative`. */
+export interface SublimeNativeBridge {
+  invoke(mod: string, method: string, args: unknown[]): Promise<unknown>;
+}
+
+/**
+ * Expose the `sublimeNative` bridge on the main world.
+ *
+ * @param contextBridge Electron's `contextBridge` (or a compatible fake).
+ * @param ipcRenderer   Electron's `ipcRenderer` (or a compatible fake).
+ */
+export function exposeNativeBridge(
+  contextBridge: ContextBridgeLike,
+  ipcRenderer: IpcRendererLike,
+): void {
+  const bridge: SublimeNativeBridge = {
+    invoke: (mod, method, args) =>
+      ipcRenderer.invoke('native:invoke', mod, method, args),
+  };
+  contextBridge.exposeInMainWorld('sublimeNative', bridge);
+}

package/src/bridge/proxy.ts

@@ -0,0 +1,31 @@
+import type { NativeMethods } from '../types';
+
+/**
+ * Build the renderer-side typed proxy for a native service.
+ *
+ * Every property access on the returned object yields a function that forwards
+ * its call to `invoke(mod, method, args)` — the single `native:invoke` IPC
+ * channel. No node dependencies enter the renderer: the proxy only knows the
+ * module name and forwards arguments, while the `M` type parameter (derived
+ * from the service authored with `defineNative`) gives end-to-end type safety.
+ *
+ * @param mod    the native service name (the registry key).
+ * @param invoke the transport: forwards `(mod, method, args)` over IPC.
+ *
+ * @example
+ * const printer = createProxy<{ print: (copies: number) => Promise<string> }>(
+ *   'printer',
+ *   invoke,
+ * );
+ * await printer.print(7); // invoke('printer', 'print', [7])
+ */
+export function createProxy<M extends NativeMethods>(
+  mod: string,
+  invoke: (mod: string, method: string, args: unknown[]) => Promise<unknown>,
+): M {
+  return new Proxy({} as M, {
+    get(_target, prop) {
+      return (...args: unknown[]) => invoke(mod, String(prop), args);
+    },
+  });
+}

package/src/client.ts

@@ -0,0 +1,33 @@
+/**
+ * Renderer-safe public API for `@sublime-ui/desktop` (`@sublime-ui/desktop/client`).
+ *
+ * This barrel re-exports ONLY the modules that are safe to pull into a web
+ * renderer bundle: nothing here transitively imports `node:*` or `electron`.
+ * An app's renderer can `import { useNative } from '@sublime-ui/desktop/client'`
+ * and webpack will never see node/electron code, regardless of tree-shaking.
+ *
+ * The main barrel (`@sublime-ui/desktop`) additionally re-exports the
+ * main-process shell + built-in services, which DO pull in node/electron; it is
+ * marked side-effect-free so a `useNative`-only import can still be shaken, but
+ * `./client` is the guaranteed-safe entry for renderer code.
+ *
+ * @remarks Author services in the main process from the main barrel (or its
+ * `./services`), and `defineNative` is exported here too so renderer-shared
+ * contract types stay reachable without crossing into node/electron.
+ */
+
+// Authoring + contract types (pure — no node/electron).
+export { defineNative } from './define-native';
+export type { NativeMethods, NativeService } from './types';
+
+// Typed error transport (pure).
+export {
+  NativeError,
+  serializeError,
+  deserializeError,
+  type SerializedError,
+} from './errors';
+
+// Renderer hook + proxy (pure — forward over the single IPC channel only).
+export { useNative } from './use-native';
+export { createProxy } from './bridge/proxy';

package/src/define-native.ts

@@ -0,0 +1,21 @@
+import type { NativeMethods, NativeService } from './types';
+
+/**
+ * Author a native service from the main process.
+ *
+ * A thin, fully-typed wrapper: it pairs a service `name` with its async
+ * `methods` so that `typeof service` preserves each method's signature.
+ * That preserved type is what the renderer contract is derived from, giving
+ * end-to-end type safety across the `native:invoke` IPC boundary.
+ *
+ * @example
+ * const printer = defineNative('printer', {
+ *   print: async (copies: number): Promise<string> => `printed ${copies}`,
+ * });
+ */
+export function defineNative<M extends NativeMethods>(
+  name: string,
+  methods: M,
+): NativeService<M> {
+  return { name, methods };
+}

package/src/errors.ts

@@ -0,0 +1,45 @@
+/**
+ * Typed error transport for the native bridge.
+ *
+ * Errors thrown by a native service in the main process are serialized to a
+ * plain {@link SerializedError} so they can cross the `native:invoke` IPC
+ * boundary, then revived into a {@link NativeError} on the renderer side.
+ */
+
+/** Plain, structured-clone-safe representation of a native error. */
+export interface SerializedError {
+  name: string;
+  message: string;
+  code?: string;
+}
+
+/** Error type rethrown on the renderer when a native call fails. */
+export class NativeError extends Error {
+  code?: string;
+
+  constructor(message: string, code?: string) {
+    super(message);
+    this.name = 'NativeError';
+    if (code !== undefined) {
+      this.code = code;
+    }
+  }
+}
+
+/** Coerce any throwable into a transport-safe {@link SerializedError}. */
+export function serializeError(e: unknown): SerializedError {
+  if (e instanceof Error) {
+    const code = (e as { code?: unknown }).code;
+    const out: SerializedError = { name: e.name, message: e.message };
+    if (typeof code === 'string') {
+      out.code = code;
+    }
+    return out;
+  }
+  return { name: 'Error', message: String(e) };
+}
+
+/** Revive a {@link SerializedError} into a {@link NativeError}. */
+export function deserializeError(s: SerializedError): NativeError {
+  return new NativeError(s.message, s.code);
+}

package/src/index.ts

@@ -0,0 +1,68 @@
+/**
+ * Public API for `@sublime-ui/desktop`.
+ *
+ * A typed native bridge over one secure generic IPC channel (`native:invoke`):
+ * author services in the main process with {@link defineNative}, register them
+ * with {@link registerNative}, dispatch them through {@link installNativeRouter}
+ * / {@link exposeNativeBridge}, and consume them in the renderer with
+ * {@link useNative}. {@link startDesktop} / {@link createWindow} provide the
+ * hardened Electron shell, and the built-in services (`fs`, `dialog`, `shell`,
+ * `clipboard`, `notifications`) cover the common cases out of the box.
+ *
+ * @remarks
+ * The renderer must import native modules type-only; the only runtime crossing
+ * is the single `native:invoke` channel.
+ */
+
+// Core authoring + contract types.
+export { defineNative } from './define-native';
+export { registerNative } from './registry';
+export type { NativeMethods, NativeService } from './types';
+
+// Typed error transport.
+export {
+  NativeError,
+  serializeError,
+  deserializeError,
+  type SerializedError,
+} from './errors';
+
+// Renderer hook + proxy.
+export { useNative } from './use-native';
+export { createProxy } from './bridge/proxy';
+
+// Main-process router + preload bridge.
+export {
+  installNativeRouter,
+  type IpcMainLike,
+  type NativeErrorEnvelope,
+} from './bridge/main-router';
+export {
+  exposeNativeBridge,
+  type ContextBridgeLike,
+  type IpcRendererLike,
+  type SublimeNativeBridge,
+} from './bridge/preload';
+
+// Hardened Electron shell.
+export {
+  createWindow,
+  type BrowserWindowLike,
+  type BrowserWindowCtor,
+  type CreateWindowOptions,
+} from './shell/create-window';
+export {
+  startDesktop,
+  type AppLike,
+  type StartDesktopOptions,
+} from './shell/main';
+
+// Built-in services.
+export {
+  fs,
+  dialog,
+  shell,
+  clipboard,
+  notifications,
+  type NotifyOptions,
+} from './services/index';

package/src/registry.ts

@@ -0,0 +1,44 @@
+/**
+ * Native service registry.
+ *
+ * Services authored in the main process are registered here; the
+ * `native:invoke` router resolves `(module, method)` pairs against this
+ * registry and dispatches. Anything not registered resolves to `undefined`,
+ * which the router treats as an unknown-method rejection.
+ */
+
+import type { NativeMethods, NativeService } from './types';
+
+const services = new Map<string, NativeService>();
+
+/** Register one or more native services, keyed by their `name`. */
+export function registerNative(toRegister: NativeService[]): void {
+  for (const service of toRegister) {
+    services.set(service.name, service);
+  }
+}
+
+/**
+ * Resolve a `(module, method)` pair to its implementation, or `undefined`
+ * when the module is unknown or the method is not exposed by it.
+ */
+export function resolve(
+  mod: string,
+  method: string,
+): ((...args: any[]) => Promise<any>) | undefined {
+  const methods: NativeMethods | undefined = services.get(mod)?.methods;
+  if (methods === undefined) {
+    return undefined;
+  }
+  // OWN-property lookup only: a renderer must never reach inherited members
+  // (`constructor`, `__proto__`, `toString`, `hasOwnProperty`, `valueOf`, …)
+  // through the prototype chain, which `methods[method]` would expose.
+  return Object.prototype.hasOwnProperty.call(methods, method)
+    ? methods[method]
+    : undefined;
+}
+
+/** Clear all registered services. Test seam. */
+export function clearRegistry(): void {
+  services.clear();
+}

package/src/services/clipboard.ts

@@ -0,0 +1,21 @@
+import { defineNative } from '../define-native';
+import { getElectron } from './get-electron';
+
+/**
+ * Built-in `clipboard` native service.
+ *
+ * Thin async wrappers over Electron's synchronous `clipboard` module so the
+ * surface stays uniform across the native bridge (every method is a Promise).
+ * The Electron module is resolved lazily so the package loads without Electron
+ * and unit tests can mock it.
+ */
+export const clipboard = defineNative('clipboard', {
+  readText: async (): Promise<string> => {
+    const { clipboard: c } = await getElectron();
+    return c.readText();
+  },
+  writeText: async (text: string): Promise<void> => {
+    const { clipboard: c } = await getElectron();
+    c.writeText(text);
+  },
+});

package/src/services/dialog.ts

@@ -0,0 +1,31 @@
+import type { MessageBoxOptions } from 'electron';
+import { defineNative } from '../define-native';
+import { getElectron } from './get-electron';
+
+/**
+ * Built-in `dialog` native service.
+ *
+ * Thin async wrappers over Electron's `dialog` module. File pickers collapse
+ * Electron's `{ canceled, filePaths }` / `{ canceled, filePath }` shapes down
+ * to a single selected path or `null` when the user cancels (or selects
+ * nothing). The Electron module is resolved lazily so the package loads
+ * without Electron and unit tests can mock it.
+ */
+export const dialog = defineNative('dialog', {
+  openFile: async (): Promise<string | null> => {
+    const { dialog: d } = await getElectron();
+    const result = await d.showOpenDialog({ properties: ['openFile'] });
+    if (result.canceled) return null;
+    return result.filePaths[0] ?? null;
+  },
+  saveFile: async (): Promise<string | null> => {
+    const { dialog: d } = await getElectron();
+    const result = await d.showSaveDialog({});
+    if (result.canceled) return null;
+    return result.filePath ?? null;
+  },
+  message: async (opts: MessageBoxOptions): Promise<void> => {
+    const { dialog: d } = await getElectron();
+    await d.showMessageBox(opts);
+  },
+});