@dormer/electron-compat 0.0.0-stage → 0.1.3

package/package.json

@@ -1,6 +1,27 @@
 {
   "name": "@dormer/electron-compat",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.3",
+  "description": "Electron-shaped adapter over @dormer/api: same module names where semantics hold, explicit NotSupportedError elsewhere",
+  "type": "module",
+  "license": "Apache-2.0 OR MIT",
+  "exports": {
+    ".": "./src/index.ts",
+    "./renderer": "./src/renderer.ts",
+    "./matrix": "./src/matrix.ts"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.ts"
+  },
+  "dependencies": {
+    "@dormer/api": "0.1.3",
+    "@dormer/renderer": "0.1.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/veerareddyvishal144/dormer.git",
+    "directory": "packages/electron-compat"
+  }
+}

package/src/index.ts

@@ -0,0 +1,61 @@
+// `import { app, BrowserWindow, ipcMain } from "@dormer/electron-compat"` works for the supported
+// surface; unsupported modules are exported as throwing stubs so failures are explicit and early.
+import * as api from "@dormer/api";
+import { MODULES } from "./matrix.ts";
+
+export class NotSupportedError extends Error {
+  readonly code = "ENOTSUP";
+  readonly module: string;
+  constructor(module: string, detail: string) {
+    super(`Electron module '${module}' is not supported by Dormer: ${detail}`);
+    this.name = "NotSupportedError"; this.module = module;
+  }
+}
+
+function unsupported(name: string): unknown {
+  const entry = MODULES[name];
+  const detail = entry ? entry.notes : "no equivalent";
+  const thrower = () => { throw new NotSupportedError(name, detail); };
+  // A callable, constructible, property-less stub: any use throws with the reason.
+  return new Proxy(function stub() {}, {
+    apply: thrower, construct: thrower,
+    get(_t, prop) { if (prop === Symbol.toPrimitive || prop === "toString") return () => `[unsupported ${name}]`; return thrower(); },
+  });
+}
+
+const anyApi = api as unknown as Record<string, unknown>;
+const pick = (name: string, dormerName = name): unknown => (dormerName in anyApi ? anyApi[dormerName] : unsupported(name));
+
+export const app = api.app;
+export const BrowserWindow = api.BrowserWindow;
+export const ipcMain = api.ipcMain;
+export const Menu = pick("Menu");
+export const MenuItem = pick("MenuItem");
+export const Tray = pick("Tray");
+export const dialog = pick("dialog");
+export const Notification = pick("Notification");
+export const clipboard = pick("clipboard");
+export const globalShortcut = pick("globalShortcut");
+export const shell = pick("shell");
+export const nativeTheme = pick("nativeTheme");
+export const screen = pick("screen");
+export const powerMonitor = pick("powerMonitor");
+export const utilityProcess = pick("utilityProcess", "BackgroundWorker");
+export const safeStorage = pick("safeStorage");
+export const session = unsupported("session");
+export const protocol = unsupported("protocol");
+export const desktopCapturer = unsupported("desktopCapturer");
+export const BrowserView = unsupported("BrowserView");
+export const autoUpdater = pick("autoUpdater", "updater");
+export const crashReporter = unsupported("crashReporter");
+export const net = unsupported("net");
+export const netLog = unsupported("netLog");
+export const MessageChannelMain = unsupported("MessageChannelMain");
+export const TouchBar = unsupported("TouchBar");
+export const systemPreferences = unsupported("systemPreferences");
+export const inAppPurchase = unsupported("inAppPurchase");
+
+// Electron code often checks process.versions.electron; give it something truthful instead.
+(process.versions as Record<string, string | undefined>).dormer ??= "0.1.0";
+
+export { MODULES, UNSUPPORTED, renderMatrixMarkdown } from "./matrix.ts";

package/src/matrix.ts

@@ -0,0 +1,49 @@
+// Compatibility matrix for Electron's main-process modules (ADR-0009). Status values:
+//   "full"     same names and semantics
+//   "partial"  present; some options/events differ or are missing (see notes)
+//   "renamed"  available under a different Dormer name
+//   "none"     cannot be reproduced on a system WebView; the adapter throws NotSupportedError
+export type Status = "full" | "partial" | "renamed" | "none";
+export interface Entry { status: Status; notes: string; dormer?: string }
+
+export const MODULES: Record<string, Entry> = {
+  app: { status: "partial", notes: "Lifecycle events (will-finish-launching, ready, window-all-closed, before-quit, will-quit, quit, activate, open-url), whenReady, quit, exit, getPath, getName, getVersion. macOS: badge, recent documents, login items (SMAppService). Missing: jump lists (Windows), GPU info, accessibility APIs; see docs/api/platform-matrix.md." },
+  BrowserWindow: { status: "partial", notes: "Options and events for size, position, title, show/hide, close/closed (cancellable), focus/blur, resized, moved, fullscreen, alwaysOnTop, drag-drop of files. loadApp() replaces loadFile(); loadURL() is restricted by the capability origin policy. macOS: vibrancy, native tabs. Missing: BrowserView, setThumbarButtons, hookWindowMessage." },
+  webContents: { status: "partial", notes: "send, executeJavaScript (main world only), openDevTools, reload, setZoomFactor, print. macOS: capturePage, printToPDF (options ignored), findInPage (found yes/no), insertCSS/removeInsertedCSS, zoom levels. Missing: session, debugger, isolated-world execution, audio mute (no WKWebView API)." },
+  ipcMain: { status: "full", notes: "handle/handleOnce/removeHandler/on. Arguments are MessagePack-serialisable values; DOM objects, functions and MessagePorts do not cross. Adds handleStream for byte streams." },
+  ipcRenderer: { status: "partial", notes: "invoke/send/on/once/removeListener via the injected bridge. No sendSync, no postMessage with MessagePort transfer.", dormer: "window.dormer / @dormer/renderer" },
+  contextBridge: { status: "renamed", notes: "Dormer injects a frozen window.dormer object itself; there is no preload script and no exposeInMainWorld. Expose app-specific helpers from your renderer bundle instead.", dormer: "window.dormer" },
+  Menu: { status: "partial", notes: "buildFromTemplate, setApplicationMenu (app menu on macOS, per-window elsewhere), popup, roles, accelerators, check/radio items. On macOS the host installs a default App/Edit/Window menu (Cmd+Q, Cmd+C/V) until setApplicationMenu is called. Missing: sharingItem, badge, sublabel/toolTip on some platforms." },
+  Tray: { status: "partial", notes: "Icon, context menu, tooltip, title (macOS), click events. Linux AppIndicator backend emits no click events and GNOME needs an extension." },
+  dialog: { status: "partial", notes: "showOpenDialog, showSaveDialog, showMessageBox. Missing: securityScopedBookmarks, showCertificateTrustDialog, showErrorBox styling." },
+  Notification: { status: "partial", notes: "title, body, silent, icon, click/close where the OS reports them. Missing: actions/reply on most platforms, toastXml, Windows activation callbacks (planned)." },
+  clipboard: { status: "partial", notes: "readText/writeText/readHTML/writeHTML/readImage/writeImage/clear; macOS bookmark and find pasteboards. Missing: selection clipboard write on Linux." },
+  globalShortcut: { status: "partial", notes: "register/unregister/isRegistered/unregisterAll. Not available on Wayland (ENOTSUP)." },
+  shell: { status: "partial", notes: "openExternal (scheme allow-list), openPath, showItemInFolder, trashItem, beep (macOS/Linux). Missing: readShortcutLink/writeShortcutLink." },
+  nativeTheme: { status: "partial", notes: "shouldUseDarkColors, updated event. themeSource applies to the page on macOS (WKWebView appearance); host-drawn UI only elsewhere." },
+  screen: { status: "partial", notes: "getPrimaryDisplay, getAllDisplays (bounds, scaleFactor); macOS: getCursorScreenPoint, display-metrics-changed. Missing elsewhere: cursor point, display-change events." },
+  powerMonitor: { status: "partial", notes: "macOS: suspend/resume/lock-screen/unlock-screen/screens-sleep/wake events, getSystemIdleTime/State. Windows/Linux planned. isOnBatteryPower not implemented." },
+  session: { status: "none", notes: "Cookies, webRequest interception, proxies, permissions handler, cache control live in the WebView engine; only subsets exist and differ per platform." },
+  protocol: { status: "renamed", notes: "dormer://app serves bundled assets with CSP; arbitrary privileged schemes (standard/secure/bypassCSP/corsEnabled flags) are not configurable.", dormer: "dormer://app (built in)" },
+  desktopCapturer: { status: "none", notes: "Requires Chromium's DesktopMediaList; use OS screen capture APIs from Node instead." },
+  webview: { status: "none", notes: "<webview> tag is Chromium-only. Use a second BrowserWindow." },
+  BrowserView: { status: "none", notes: "Multiple web contents composited in one window are possible via child webviews in WRY but not exposed yet." },
+  utilityProcess: { status: "renamed", notes: "Use BackgroundWorker (worker_threads with the Dormer frame protocol) or child_process from Node.", dormer: "BackgroundWorker" },
+  autoUpdater: { status: "renamed", notes: "Dormer ships a cross-platform updater with Ed25519-signed manifests (host.updater.*).", dormer: "updater" },
+  safeStorage: { status: "partial", notes: "macOS: AES-256-GCM with the key in the login Keychain. DPAPI and Secret Service planned." },
+  crashReporter: { status: "none", notes: "Not provided; use process.report / a Node crash reporter." },
+  net: { status: "renamed", notes: "Use Node's fetch/undici in the backend.", dormer: "node:http / fetch" },
+  netLog: { status: "none", notes: "Chromium network log is not available." },
+  inAppPurchase: { status: "none", notes: "Not provided." },
+  systemPreferences: { status: "none", notes: "Not provided." },
+  TouchBar: { status: "none", notes: "Not provided." },
+  MessageChannelMain: { status: "none", notes: "MessagePorts do not cross the WebView boundary on system WebViews." },
+  process: { status: "partial", notes: "Plain Node process object in the backend; process.versions.electron is absent, process.versions.dormer is set by the adapter." },
+};
+
+export const UNSUPPORTED = Object.entries(MODULES).filter(([, e]) => e.status === "none").map(([k]) => k);
+
+export function renderMatrixMarkdown(): string {
+  const rows = Object.entries(MODULES).map(([name, e]) => `| \`${name}\` | ${e.status} | ${e.dormer ? `\`${e.dormer}\`` : ""} | ${e.notes} |`);
+  return ["| Electron module | Status | Dormer equivalent | Notes |", "|---|---|---|---|", ...rows].join("\n");
+}

package/src/renderer.ts

@@ -0,0 +1,18 @@
+// `ipcRenderer` shim for renderer code written against Electron, backed by the injected bridge.
+import { invoke as dInvoke, send as dSend, on as dOn, once as dOnce, isDormer } from "@dormer/renderer";
+
+type Listener = (event: { senderId: number }, ...args: any[]) => void;
+const offs = new Map<Listener, () => void>();
+const EV = { senderId: 0 };
+
+export const ipcRenderer = {
+  invoke<T = unknown>(channel: string, ...args: unknown[]): Promise<T> { return dInvoke<T>(channel, ...args); },
+  send(channel: string, ...args: unknown[]): void { dSend(channel, ...args); },
+  on(channel: string, listener: Listener): typeof ipcRenderer { offs.set(listener, dOn(channel, (...args) => listener(EV, ...args))); return ipcRenderer; },
+  once(channel: string, listener: Listener): typeof ipcRenderer { offs.set(listener, dOnce(channel, (...args) => listener(EV, ...args))); return ipcRenderer; },
+  removeListener(_channel: string, listener: Listener): typeof ipcRenderer { offs.get(listener)?.(); offs.delete(listener); return ipcRenderer; },
+  removeAllListeners(_channel?: string): typeof ipcRenderer { for (const off of offs.values()) off(); offs.clear(); return ipcRenderer; },
+  sendSync(): never { throw new Error("ipcRenderer.sendSync is not supported by Dormer (no synchronous IPC on system WebViews); use invoke"); },
+  postMessage(): never { throw new Error("ipcRenderer.postMessage with MessagePort transfer is not supported by Dormer"); },
+};
+export const isElectronLike = isDormer;

package/test/compat.test.ts

@@ -0,0 +1,26 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+test("matrix is consistent and renders", async () => {
+  const { MODULES, UNSUPPORTED, renderMatrixMarkdown } = await import("../src/matrix.ts");
+  assert.ok(Object.keys(MODULES).length > 25);
+  assert.ok(UNSUPPORTED.includes("session") && UNSUPPORTED.includes("desktopCapturer"));
+  const md = renderMatrixMarkdown();
+  assert.match(md, /\| `ipcMain` \| full \|/);
+});
+
+test("unsupported stubs throw NotSupportedError with the reason", async () => {
+  // @dormer/api connects to the host when imported; give it a dummy channel first (as app.test.ts does).
+  const net = await import("node:net");
+  const { HostChannel } = await import("@dormer/node-runtime");
+  const { initRuntime } = await import("../../api/src/runtime.ts");
+  const server = net.createServer(); await new Promise<void>((r) => server.listen(0, "127.0.0.1", r));
+  const port = (server.address() as import("node:net").AddressInfo).port;
+  const sock = await new Promise<import("node:net").Socket>((r) => { const s = net.connect(port, "127.0.0.1", () => r(s)); });
+  initRuntime(new HostChannel(sock));
+  const mod = await import("../src/index.ts").catch((e) => { throw new Error("adapter import failed: " + e.message); });
+  assert.throws(() => (mod.session as any).defaultSession, (e: Error) => e.name === "NotSupportedError" && /session/.test(e.message));
+  assert.throws(() => new (mod.BrowserView as any)(), /BrowserView/);
+  assert.equal(typeof mod.ipcMain.handle, "function");
+  sock.destroy(); server.close();
+});

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.