@sublime-ui/desktop 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aaron Mkandawire and Sublime UI 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,47 @@
+# @sublime-ui/desktop
+
+Electron desktop packaging and a secure **native bridge** for
+[Sublime UI](https://sublime-ui.github.io/sublime-ui/) apps. The desktop target
+renders your existing **web** UI and adds access to native capabilities.
+
+Define a native service in the main process and call it from the renderer with a
+typed hook. Everything travels over one generic, `contextIsolation`-safe IPC
+channel.
+
+```ts
+// main process — define + register
+import { defineNative, registerNative } from '@sublime-ui/desktop';
+export const greeter = defineNative('greeter', {
+  async hello(name: string) { return `Hello, ${name}!`; },
+});
+registerNative([greeter]);
+```
+
+```ts
+// renderer — renderer-safe entry, returns null on web/mobile
+import { useNative } from '@sublime-ui/desktop/client';
+const greeter = useNative<typeof import('./greeter').greeter>('greeter');
+await greeter?.hello('world');
+```
+
+Built-in services cover `fs`, `dialog`, `shell`, `clipboard`, and
+`notifications`. Packaging uses Electron Forge via
+`sublime desktop:dev` / `sublime desktop:build`.
+
+> Import renderer code from `@sublime-ui/desktop/client` — it contains **no**
+> node/electron and is safe to bundle into the web build.
+
+## Install
+
+```bash
+npm install @sublime-ui/desktop
+```
+
+## Documentation
+
+The native bridge and packaging:
+**https://sublime-ui.github.io/sublime-ui/docs/desktop/overview**
+
+## License
+
+MIT

package/dist/bridge/main-router.d.ts

@@ -0,0 +1,30 @@
+import { SerializedError } from '../errors.js';
+
+/**
+ * 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.
+ */
+
+/** Envelope returned over IPC when a native call fails. */
+interface NativeErrorEnvelope {
+    __nativeError: SerializedError;
+}
+/** Minimal `ipcMain` surface needed to register the channel. Injectable. */
+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).
+ */
+declare function installNativeRouter(ipcMain: IpcMainLike): void;
+
+export { type IpcMainLike, type NativeErrorEnvelope, installNativeRouter };

package/dist/bridge/main-router.js

@@ -0,0 +1,22 @@
+import { resolve } from "../registry";
+import { NativeError, serializeError } from "../errors";
+function installNativeRouter(ipcMain) {
+  ipcMain.handle(
+    "native:invoke",
+    async (_event, mod, method, args = []) => {
+      try {
+        const fn = resolve(mod, method);
+        if (fn === void 0) {
+          throw new NativeError(`Unknown native method ${mod}:${method}`);
+        }
+        return await fn(...args);
+      } catch (e) {
+        const envelope = { __nativeError: serializeError(e) };
+        return envelope;
+      }
+    }
+  );
+}
+export {
+  installNativeRouter
+};

package/dist/bridge/preload.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 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. */
+interface ContextBridgeLike {
+    exposeInMainWorld(key: string, api: unknown): void;
+}
+/** Minimal `ipcRenderer` surface needed to forward invocations. Injectable. */
+interface IpcRendererLike {
+    invoke(channel: string, ...args: any[]): Promise<unknown>;
+}
+/** Shape exposed at `window.sublimeNative`. */
+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).
+ */
+declare function exposeNativeBridge(contextBridge: ContextBridgeLike, ipcRenderer: IpcRendererLike): void;
+
+export { type ContextBridgeLike, type IpcRendererLike, type SublimeNativeBridge, exposeNativeBridge };

package/dist/bridge/preload.js

@@ -0,0 +1,9 @@
+function exposeNativeBridge(contextBridge, ipcRenderer) {
+  const bridge = {
+    invoke: (mod, method, args) => ipcRenderer.invoke("native:invoke", mod, method, args)
+  };
+  contextBridge.exposeInMainWorld("sublimeNative", bridge);
+}
+export {
+  exposeNativeBridge
+};

package/dist/bridge/proxy.d.ts

@@ -0,0 +1,24 @@
+import { NativeMethods } from '../types.js';
+
+/**
+ * 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])
+ */
+declare function createProxy<M extends NativeMethods>(mod: string, invoke: (mod: string, method: string, args: unknown[]) => Promise<unknown>): M;
+
+export { createProxy };

package/dist/bridge/proxy.js

@@ -0,0 +1,10 @@
+function createProxy(mod, invoke) {
+  return new Proxy({}, {
+    get(_target, prop) {
+      return (...args) => invoke(mod, String(prop), args);
+    }
+  });
+}
+export {
+  createProxy
+};

package/dist/client.d.ts

@@ -0,0 +1,5 @@
+export { defineNative } from './define-native.js';
+export { NativeMethods, NativeService } from './types.js';
+export { NativeError, SerializedError, deserializeError, serializeError } from './errors.js';
+export { useNative } from './use-native.js';
+export { createProxy } from './bridge/proxy.js';

package/dist/client.js

@@ -0,0 +1,16 @@
+import { defineNative } from "./define-native";
+import {
+  NativeError,
+  serializeError,
+  deserializeError
+} from "./errors";
+import { useNative } from "./use-native";
+import { createProxy } from "./bridge/proxy";
+export {
+  NativeError,
+  createProxy,
+  defineNative,
+  deserializeError,
+  serializeError,
+  useNative
+};

package/dist/define-native.d.ts

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

package/dist/define-native.js

@@ -0,0 +1,6 @@
+function defineNative(name, methods) {
+  return { name, methods };
+}
+export {
+  defineNative
+};

package/dist/errors.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 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. */
+interface SerializedError {
+    name: string;
+    message: string;
+    code?: string;
+}
+/** Error type rethrown on the renderer when a native call fails. */
+declare class NativeError extends Error {
+    code?: string;
+    constructor(message: string, code?: string);
+}
+/** Coerce any throwable into a transport-safe {@link SerializedError}. */
+declare function serializeError(e: unknown): SerializedError;
+/** Revive a {@link SerializedError} into a {@link NativeError}. */
+declare function deserializeError(s: SerializedError): NativeError;
+
+export { NativeError, type SerializedError, deserializeError, serializeError };

package/dist/errors.js

@@ -0,0 +1,29 @@
+class NativeError extends Error {
+  code;
+  constructor(message, code) {
+    super(message);
+    this.name = "NativeError";
+    if (code !== void 0) {
+      this.code = code;
+    }
+  }
+}
+function serializeError(e) {
+  if (e instanceof Error) {
+    const code = e.code;
+    const out = { name: e.name, message: e.message };
+    if (typeof code === "string") {
+      out.code = code;
+    }
+    return out;
+  }
+  return { name: "Error", message: String(e) };
+}
+function deserializeError(s) {
+  return new NativeError(s.message, s.code);
+}
+export {
+  NativeError,
+  deserializeError,
+  serializeError
+};

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+export { defineNative } from './define-native.js';
+export { registerNative } from './registry.js';
+export { NativeMethods, NativeService } from './types.js';
+export { NativeError, SerializedError, deserializeError, serializeError } from './errors.js';
+export { useNative } from './use-native.js';
+export { createProxy } from './bridge/proxy.js';
+export { IpcMainLike, NativeErrorEnvelope, installNativeRouter } from './bridge/main-router.js';
+export { ContextBridgeLike, IpcRendererLike, SublimeNativeBridge, exposeNativeBridge } from './bridge/preload.js';
+export { BrowserWindowCtor, BrowserWindowLike, CreateWindowOptions, createWindow } from './shell/create-window.js';
+export { AppLike, StartDesktopOptions, startDesktop } from './shell/main.js';
+export { fs } from './services/fs.js';
+export { dialog } from './services/dialog.js';
+export { shell } from './services/shell.js';
+export { clipboard } from './services/clipboard.js';
+export { NotifyOptions, notifications } from './services/notifications.js';
+import 'electron';

package/dist/index.js

@@ -0,0 +1,46 @@
+import { defineNative } from "./define-native";
+import { registerNative } from "./registry";
+import {
+  NativeError,
+  serializeError,
+  deserializeError
+} from "./errors";
+import { useNative } from "./use-native";
+import { createProxy } from "./bridge/proxy";
+import {
+  installNativeRouter
+} from "./bridge/main-router";
+import {
+  exposeNativeBridge
+} from "./bridge/preload";
+import {
+  createWindow
+} from "./shell/create-window";
+import {
+  startDesktop
+} from "./shell/main";
+import {
+  fs,
+  dialog,
+  shell,
+  clipboard,
+  notifications
+} from "./services/index";
+export {
+  NativeError,
+  clipboard,
+  createProxy,
+  createWindow,
+  defineNative,
+  deserializeError,
+  dialog,
+  exposeNativeBridge,
+  fs,
+  installNativeRouter,
+  notifications,
+  registerNative,
+  serializeError,
+  shell,
+  startDesktop,
+  useNative
+};

package/dist/registry.d.ts

@@ -0,0 +1,22 @@
+import { NativeService } from './types.js';
+
+/**
+ * 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.
+ */
+
+/** Register one or more native services, keyed by their `name`. */
+declare function registerNative(toRegister: NativeService[]): void;
+/**
+ * Resolve a `(module, method)` pair to its implementation, or `undefined`
+ * when the module is unknown or the method is not exposed by it.
+ */
+declare function resolve(mod: string, method: string): ((...args: any[]) => Promise<any>) | undefined;
+/** Clear all registered services. Test seam. */
+declare function clearRegistry(): void;
+
+export { clearRegistry, registerNative, resolve };

package/dist/registry.js

@@ -0,0 +1,21 @@
+const services = /* @__PURE__ */ new Map();
+function registerNative(toRegister) {
+  for (const service of toRegister) {
+    services.set(service.name, service);
+  }
+}
+function resolve(mod, method) {
+  const methods = services.get(mod)?.methods;
+  if (methods === void 0) {
+    return void 0;
+  }
+  return Object.prototype.hasOwnProperty.call(methods, method) ? methods[method] : void 0;
+}
+function clearRegistry() {
+  services.clear();
+}
+export {
+  clearRegistry,
+  registerNative,
+  resolve
+};

package/dist/services/clipboard.d.ts

@@ -0,0 +1,16 @@
+import { NativeService } from '../types.js';
+
+/**
+ * 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.
+ */
+declare const clipboard: NativeService<{
+    readText: () => Promise<string>;
+    writeText: (text: string) => Promise<void>;
+}>;
+
+export { clipboard };

package/dist/services/clipboard.js

@@ -0,0 +1,15 @@
+import { defineNative } from "../define-native";
+import { getElectron } from "./get-electron";
+const clipboard = defineNative("clipboard", {
+  readText: async () => {
+    const { clipboard: c } = await getElectron();
+    return c.readText();
+  },
+  writeText: async (text) => {
+    const { clipboard: c } = await getElectron();
+    c.writeText(text);
+  }
+});
+export {
+  clipboard
+};

package/dist/services/dialog.d.ts

@@ -0,0 +1,19 @@
+import { NativeService } from '../types.js';
+import { MessageBoxOptions } from '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.
+ */
+declare const dialog: NativeService<{
+    openFile: () => Promise<string | null>;
+    saveFile: () => Promise<string | null>;
+    message: (opts: MessageBoxOptions) => Promise<void>;
+}>;
+
+export { dialog };

package/dist/services/dialog.js

@@ -0,0 +1,23 @@
+import { defineNative } from "../define-native";
+import { getElectron } from "./get-electron";
+const dialog = defineNative("dialog", {
+  openFile: async () => {
+    const { dialog: d } = await getElectron();
+    const result = await d.showOpenDialog({ properties: ["openFile"] });
+    if (result.canceled) return null;
+    return result.filePaths[0] ?? null;
+  },
+  saveFile: async () => {
+    const { dialog: d } = await getElectron();
+    const result = await d.showSaveDialog({});
+    if (result.canceled) return null;
+    return result.filePath ?? null;
+  },
+  message: async (opts) => {
+    const { dialog: d } = await getElectron();
+    await d.showMessageBox(opts);
+  }
+});
+export {
+  dialog
+};

package/dist/services/fs.d.ts

@@ -0,0 +1,20 @@
+import { NativeService } from '../types.js';
+
+/**
+ * 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.
+ */
+declare const fs: NativeService<{
+    readFile: (path: string) => Promise<string>;
+    writeFile: (path: string, data: string) => Promise<void>;
+    exists: (path: string) => Promise<boolean>;
+    readDir: (path: string) => Promise<string[]>;
+    mkdir: (path: string) => Promise<void>;
+    remove: (path: string) => Promise<void>;
+}>;
+
+export { fs };

package/dist/services/fs.js

@@ -0,0 +1,26 @@
+import { readFile, writeFile, readdir, mkdir as mkdirFs, rm, access } from "node:fs/promises";
+import { defineNative } from "../define-native";
+const fs = defineNative("fs", {
+  readFile: (path) => readFile(path, "utf8"),
+  writeFile: async (path, data) => {
+    await writeFile(path, data, "utf8");
+  },
+  exists: async (path) => {
+    try {
+      await access(path);
+      return true;
+    } catch {
+      return false;
+    }
+  },
+  readDir: (path) => readdir(path),
+  mkdir: async (path) => {
+    await mkdirFs(path, { recursive: true });
+  },
+  remove: async (path) => {
+    await rm(path, { recursive: true, force: true });
+  }
+});
+export {
+  fs
+};

package/dist/services/get-electron.d.ts

@@ -0,0 +1,14 @@
+import * 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', …)`.
+ */
+declare function getElectron(): Promise<typeof Electron>;
+
+export { getElectron };

package/dist/services/get-electron.js

@@ -0,0 +1,6 @@
+async function getElectron() {
+  return import("electron");
+}
+export {
+  getElectron
+};

package/dist/services/index.d.ts

@@ -0,0 +1,7 @@
+export { fs } from './fs.js';
+export { dialog } from './dialog.js';
+export { shell } from './shell.js';
+export { clipboard } from './clipboard.js';
+export { NotifyOptions, notifications } from './notifications.js';
+import '../types.js';
+import 'electron';

package/dist/services/index.js

@@ -0,0 +1,12 @@
+import { fs } from "./fs";
+import { dialog } from "./dialog";
+import { shell } from "./shell";
+import { clipboard } from "./clipboard";
+import { notifications } from "./notifications";
+export {
+  clipboard,
+  dialog,
+  fs,
+  notifications,
+  shell
+};

package/dist/services/notifications.d.ts

@@ -0,0 +1,21 @@
+import { NativeService } from '../types.js';
+
+/** Options for {@link notifications}'s `notify` method. */
+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.
+ */
+declare const notifications: NativeService<{
+    notify: ({ title, body }: NotifyOptions) => Promise<void>;
+}>;
+
+export { type NotifyOptions, notifications };

package/dist/services/notifications.js

@@ -0,0 +1,11 @@
+import { defineNative } from "../define-native";
+import { getElectron } from "./get-electron";
+const notifications = defineNative("notifications", {
+  notify: async ({ title, body }) => {
+    const { Notification } = await getElectron();
+    new Notification({ title, body }).show();
+  }
+});
+export {
+  notifications
+};

package/dist/services/shell.d.ts

@@ -0,0 +1,16 @@
+import { NativeService } from '../types.js';
+
+/**
+ * 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.
+ */
+declare const shell: NativeService<{
+    openExternal: (url: string) => Promise<void>;
+    openPath: (path: string) => Promise<void>;
+    showItemInFolder: (path: string) => Promise<void>;
+}>;
+
+export { shell };