jops-core 1.1.4 → 1.1.6

package/README.md

@@ -19,10 +19,12 @@ No Webpack. No Babel. No compiler. Just `<script type="module">` and a browser.
 | Angular   | ❌            | ✅          | ✅                       | ✅                             |
 | Svelte    | ❌ (compiler) | ✅          | ✅                       | ✅                             |
 
-**Target audience:** Teams building internal tools, dashboards, embedded WebViews, or native mobile hybrid apps who want a structured, class-based frontend architecture without the npm/webpack/babel ecosystem overhead.
+**Target audience:** Teams building internal tools, dashboards, embedded WebViews, native mobile hybrid apps, or desktop apps who want a structured, class-based frontend architecture without the npm/webpack/babel ecosystem overhead.
 
 **Next.js teams:** a JOPS SPA can also run inside a Next.js page, next to React, with Next.js as its backend. See [Next.js Integration](#nextjs-integration).
 
+**Desktop apps:** a JOPS SPA can be the UI of an Electron app on macOS, Windows and Linux, with no bundler. See [Desktop Apps (Electron)](#desktop-apps-electron).
+
 **WordPress sites:** a JOPS SPA can run inside a WordPress page (Elementor or the block editor) through the JOPS plugin and its `[jops]` shortcode. See [WordPress Integration](#wordpress-integration).
 
 ---
@@ -92,7 +94,8 @@ npx jops-core init
 | 1 | Empty JOPS project: the basic skeleton of a JOPS app |
 | 2 | Hello World JOPS project: an example app using every feature |
 | 3 | Next.js JOPS Embedded SPA: a Next.js project hosting a JOPS SPA (see [Next.js Integration](#nextjs-integration)) |
-| 4 | None: only the library, `index.html` and scripts |
+| 4 | Electron JOPS Desktop App: an Electron Forge project whose UI is a JOPS SPA (see [Desktop Apps (Electron)](#desktop-apps-electron)) |
+| 5 | None: only the library, `index.html` and scripts |
 
 ### Updating the library
 
@@ -295,6 +298,126 @@ A `cordova_plugins.js` "not found" error in the console is expected when the pro
 
 ---
 
+## Desktop Apps (Electron)
+
+A JOPS SPA can be the UI (renderer process) of an [Electron](https://www.electronjs.org/) app. The page is loaded from disk with `loadFile()`, JOPS and the app's files are packaged as they are (no bundler), and the views reach the operating system through Electron's preload bridge. Tested with Electron 45 and Electron Forge 8 on macOS and Windows.
+
+### Quick start: the Electron template
+
+In an empty folder (or a fresh npm project):
+
+```bash
+npx jops-core init
+```
+
+and pick **4. Electron JOPS Desktop App**. `init` writes an Electron Forge project into the current folder, merges its dependencies and scripts into an existing `package.json` (existing entries are kept), vendors the library and runs `npm install`. Then:
+
+```bash
+npm start          # run the app
+npm run make       # package it (out/make/)
+```
+
+| Path | Process | What it is |
+| --- | --- | --- |
+| `src/main.js` | main | Creates the window and answers two IPC calls: `app:info` and `files:list` |
+| `src/preload.js` | preload | Exposes only those two functions to the page, as `window.api.*` |
+| `src/index.html` | renderer | Content-Security-Policy, import map, jops-core script (`data-app="App.js"`) |
+| `src/App.js`, `src/layout/main.html` | renderer | Root view: a sidebar and `<Router jops screens>` |
+| `src/HomeView.js`, `src/FilesView.js` | renderer | Two screens that call `window.api` |
+| `src/lib/jops-core.min.js` | renderer | The JOPS library, vendored |
+
+`init` refuses to run in a folder that already has an Electron project (`forge.config.*`, `src/index.html`, `src/App.js`, or a `"main"` file) and changes nothing there; use the setup below instead.
+
+### Adding JOPS to an existing Electron project
+
+```bash
+npm i -D jops-core
+npx jops-core init
+```
+
+`init` recognises an Electron project by `electron` in `package.json`; pick template 1, 2 or 5. It works with Electron Forge's default template (`npx create-electron-app@latest my-app`) and other projects that load a plain HTML page; Forge's **vite** and **webpack** templates build the page with a bundler and are not supported. What `init` configures:
+
+- The **web folder** is the folder of the page the main process loads: the folder of `"main"` when it has an `index.html` (`src/` in Forge's template).
+- The library goes to `<web folder>/lib/jops-core.min.js`.
+- Forge's sample page is moved to `index.forge.html` and replaced by a JOPS `index.html` with a Content-Security-Policy, the import map and the module script. A page you already changed is patched instead.
+- Templates 1 and 2 are copied into the web folder next to `index.html` (`App.js`, `layout/`, …), with their paths made page-relative (see below).
+- `jops-core` moves to `devDependencies` and a `jops:update` script is added. No `build` or `postinstall` script: Electron Forge packages the web folder itself.
+
+After upgrading jops-core, copy the new library into the app:
+
+```bash
+npm i -D jops-core@latest
+npm run jops:update
+```
+
+### Paths under `file://`
+
+The page is loaded from `file://`, where a leading `/` means the root of the disk. Every path JOPS resolves (`data-app`, `src=`, `layout=`, `loadLayout()`, `setStyle()`) is written **relative to the page, without a leading `./` or `/`**:
+
+```html
+<script type="module" src="lib/jops-core.min.js" data-app="App.js"></script>
+```
+
+```html
+<FilesView jops src="FilesView.js" layout="layout/files_view.html" path="/files"></FilesView>
+```
+
+The import map is read by the browser, not by JOPS, and its value must look like a URL, so it keeps its `./`: `{ "imports": { "jops-core": "./lib/jops-core.min.js" } }`. The same applies to `<img src>` and other URLs in your markup: `assets/logo.svg`, not `/assets/logo.svg`. Packaging changes nothing: the files are read from inside `app.asar` with the same relative paths.
+
+### Calling the main process (IPC)
+
+JOPS adds no IPC layer: Electron's preload script and `contextBridge` are the bridge, and views call the functions it exposes, the same way Cordova plugins are called from `window`.
+
+```js
+// src/main.js
+ipcMain.handle("files:list", async () => { /* … */ return { dir, entries }; });
+
+// src/preload.js
+contextBridge.exposeInMainWorld("api", {
+  listFiles: () => ipcRenderer.invoke("files:list"),
+});
+
+// src/FilesView.js
+async onResume() {
+  if (!window.api) return; // opened in a regular browser
+  const { dir, entries } = await window.api.listFiles();
+  // …
+}
+```
+
+- Expose named functions only, never `ipcRenderer` itself, and validate arguments in the main process.
+- **Events from the main process** (notifications, live data): `webContents.send()` in the main process, and in the preload a function that registers a listener and returns its unsubscribe function:
+
+  ```js
+  // src/preload.js
+  onProgress: (callback) => {
+    const listener = (event, value) => callback(value);
+    ipcRenderer.on("progress", listener);
+    return () => ipcRenderer.removeListener("progress", listener);
+  },
+  ```
+
+  A view subscribes in `onResume()` and unsubscribes in `onPause()` or `destroy()`, or forwards the data into an owned `EventBus` subscription (`EventBus.subscribe(this, …)`), which `destroy()` removes.
+
+### Content-Security-Policy
+
+`init` writes this policy into `index.html`, so Electron shows no security warning:
+
+```html
+<meta http-equiv="Content-Security-Policy"
+  content="default-src 'self'; script-src 'self' 'unsafe-inline' blob:; style-src 'self' 'unsafe-inline'; img-src 'self' data:" />
+```
+
+Only the app's own files load. `'unsafe-inline'` is needed for the inline import map and the `on*` attributes that `bindEvents()` wires, `blob:` for `Thread` workers. Remote scripts and `eval` stay blocked. Add hosts as your app needs them, e.g. `connect-src 'self' https://api.example.com` before calling a remote API.
+
+### Conventions
+
+- **Screens mode** (`<Router jops screens>`) suits desktop layouts: each route fills the router area and scrolls on its own, below a fixed sidebar or toolbar.
+- Keep **Electron's secure defaults** (`contextIsolation`, `sandbox`, no `nodeIntegration`); the views need nothing else.
+- `jops-core` is a **devDependency**: the app uses the vendored copy, so the npm package (with its CLI and templates) stays out of `app.asar`.
+
+---
+
 ## Next.js Integration
 
 A JOPS SPA can run inside a page of a Next.js (App Router) app. Next.js keeps what it does best (server rendering, data, Route Handlers, its own routing and React ecosystem) and the JOPS app adds class-based views with an Android-style lifecycle on the pages that need them. Both render on the same page:
@@ -842,6 +965,7 @@ Add the `screens` attribute to give the Router a container of its own, with ever
 - The `<Router>` tag is replaced by `<div class="jops-router">` (plus the tag's own `id` and `class`), styled `position: relative; overflow: hidden`. Its routes are placed inside it, not in the tag's parent element.
 - **Give the container its size in your CSS**, e.g. fill the rest of a flex column: `.jops-router { flex: 1; min-height: 0; }`. Without a height it has none, and nothing is visible.
 - Each route and each view opened with `navigate()` or `replace()` is wrapped in a `<div class="jops-screen">` that fills the container (`position: absolute; inset: 0`), **scrolls on its own** (`overflow: auto`) and has an opaque background. Set the background with the `--jops-screen-bg` CSS variable (default `Canvas`, the browser's page colour in light and dark mode): `.jops-router { --jops-screen-bg: var(--bg); }`.
+- **Styling screens:** `.jops-screen` and `.jops-router` are hooks for your own CSS, e.g. padding inside every screen: `.jops-screen { padding: 0 24px 32px; }`. The properties the Router sets inline (`position`, `inset`, `overflow` and `background` on screens; `position` and `overflow` on the container) take precedence over your stylesheet; use `--jops-screen-bg` for the background.
 - A new view **covers** the current one, which stays alive underneath. During the transition both are visible; afterwards the covered screen is `visibility: hidden` and `inert` (not painted, not focusable), so it keeps its scroll position and is shown again unchanged on Back. Inactive flat routes are hidden the same way.
 - `slide` and `fade` move only the upper screen (the new one forward, the leaving one on Back), and also work for views with several top-level elements.
 - Without `screens` (the default), routes are placed in the parent element and scroll with the page, as before.
@@ -986,12 +1110,12 @@ t.terminate();
 
 | Command                | Description                                                                |
 | ---------------------- | -------------------------------------------------------------------------- |
-| `npx jops-core init`   | Vendor library, configure `index.html`, inject scripts into `package.json`. Detects Cordova and Capacitor projects (see [Hybrid Mobile Apps](#hybrid-mobile-apps-cordova-ionic--capacitor)). Template 3 creates a Next.js project instead (see [Next.js Integration](#nextjs-integration)) |
+| `npx jops-core init`   | Vendor library, configure `index.html`, inject scripts into `package.json`. Detects Cordova and Capacitor projects (see [Hybrid Mobile Apps](#hybrid-mobile-apps-cordova-ionic--capacitor)) and Electron projects (see [Desktop Apps (Electron)](#desktop-apps-electron)). Template 3 creates a Next.js project and template 4 an Electron project instead |
 | `npx jops-core init --wp` | Install the JOPS WordPress plugin: into `plugins/jops/` of a `wp-env` project, otherwise into the plugins folder of the WordPress installation found in this folder or above it (see [WordPress Integration](#wordpress-integration)) |
-| `npx jops-core update` | Copy the latest `jops-core.min.js` from `node_modules` to `lib/` (`public/lib/` in a Next.js project); also refreshes an installed JOPS WordPress plugin |
-| `npx jops-core build`  | Generate production-ready `dist/` folder (skipped in Cordova/Capacitor projects) |
+| `npx jops-core update` | Copy the latest `jops-core.min.js` from `node_modules` to `lib/` (`public/lib/` in a Next.js project, `src/lib/` in an Electron project); also refreshes an installed JOPS WordPress plugin |
+| `npx jops-core build`  | Generate production-ready `dist/` folder (skipped in Cordova/Capacitor and Electron projects) |
 
-`init` and `update` accept `--cordova`, `--capacitor` or `--web` to override the detected project type, and `--wp-root <path>` to point to a WordPress folder instead of searching for it (implies `--wp`).
+`init` and `update` accept `--cordova`, `--capacitor`, `--electron` or `--web` to override the detected project type, and `--wp-root <path>` to point to a WordPress folder instead of searching for it (implies `--wp`).
 
 After each command the CLI checks npm for a newer jops-core and prints a notice if one is available (at most 1.5 s, silent when offline). `build` also warns if `lib/jops-core.min.js` doesn't match the installed version. Turn the check off with `--no-update-check` or `JOPS_NO_UPDATE_CHECK=1`; it is skipped automatically when `CI` is set.
 

package/bin/init.js

@@ -14,12 +14,13 @@ if (command !== "init" && command !== "build" && command !== "update") {
   console.log("  npx jops-core init --wp  — install the JOPS WordPress plugin: into plugins/jops/ of a wp-env project");
   console.log("                             (folder with .wp-env.json), otherwise into the plugins folder of the");
   console.log("                             WordPress installation found in this folder or above it");
-  console.log("  npx jops-core update  — copy the latest jops-core.min.js to lib/ (public/lib/ in a Next.js project);");
+  console.log("  npx jops-core update  — copy the latest jops-core.min.js to lib/ (public/lib/ in a Next.js project,");
+  console.log("                          src/lib/ in an Electron project);");
   console.log("                          also refreshes an installed JOPS WordPress plugin (found as for init --wp)");
   console.log("  npx jops-core build   — generate production-ready dist/ folder");
   console.log("");
   console.log("Options (init, update):");
-  console.log("  --cordova | --capacitor | --web   override the detected project type");
+  console.log("  --cordova | --capacitor | --electron | --web   override the detected project type");
   console.log("  --wp-root <path>                  WordPress folder to use instead of searching (implies --wp)");
   console.log("Options (all commands):");
   console.log("  --no-update-check                 skip the check for a newer jops-core version");
@@ -84,7 +85,7 @@ function isNewer(a, b) {
 // projectRoot: package.json, .vscode/   webRoot: index.html, lib/, src/
 // They differ in hybrid projects: Cordova serves www/, Capacitor serves its webDir.
 
-const forced = ["--cordova", "--capacitor", "--web"]
+const forced = ["--cordova", "--capacitor", "--electron", "--web"]
   .find((f) => flags.includes(f))?.slice(2);
 
 function readCapacitorWebDir(dir) {
@@ -112,7 +113,66 @@ function detectHybrid(dir) {
   return null;
 }
 
+// Electron: a package.json with electron in (dev)dependencies. The web folder is
+// the folder of the page the main process loads: the folder of "main" when it
+// has an index.html (Forge's default template: src/), otherwise src/ or the
+// project root when they have one, otherwise the folder of "main".
+// Bundler templates (Forge vite/webpack) build the page, so JOPS cannot be used there.
+function readPackageJson(dir) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(dir, "package.json"), "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function isElectronPackage(p) {
+  return Boolean(p?.dependencies?.electron || p?.devDependencies?.electron);
+}
+
+function electronWebRoot(dir, p) {
+  const mainDir = path.dirname(path.resolve(dir, p?.main ?? "index.js"));
+  for (const candidate of [mainDir, path.join(dir, "src"), dir]) {
+    if (fs.existsSync(path.join(candidate, "index.html"))) return candidate;
+  }
+  return mainDir;
+}
+
+function isElectronBundler(dir, p) {
+  if (/(^|[\\/])\.(vite|webpack)([\\/]|$)/.test(p?.main ?? "")) return true;
+  return ["forge.config.js", "forge.config.cjs", "forge.config.mjs", "forge.config.ts"].some((f) => {
+    const file = path.join(dir, f);
+    return fs.existsSync(file) && /plugin-(vite|webpack)/.test(fs.readFileSync(file, "utf8"));
+  });
+}
+
+function detectElectron(dir, force = false) {
+  const p = readPackageJson(dir);
+  if (!p || (!force && !isElectronPackage(p))) return null;
+  return { type: "electron", webRoot: electronWebRoot(dir, p), bundler: isElectronBundler(dir, p) };
+}
+
 function resolveProject(cwd) {
+  if (forced === "electron") {
+    const here = detectElectron(cwd, true);
+    if (here) return { ...here, projectRoot: cwd };
+    for (let dir = path.dirname(cwd); dir !== path.dirname(dir); dir = path.dirname(dir)) {
+      const up = detectElectron(dir, true);
+      if (up) return { ...up, projectRoot: dir };
+    }
+    return { type: "electron", projectRoot: cwd, webRoot: cwd, bundler: false };
+  }
+  if (!forced && !detectHybrid(cwd)) {
+    const here = detectElectron(cwd);
+    if (here) return { ...here, projectRoot: cwd };
+    // Run from inside the web folder (src/): find the Electron project above.
+    for (let dir = path.dirname(cwd); dir !== path.dirname(dir); dir = path.dirname(dir)) {
+      const up = detectElectron(dir);
+      if (!up) continue;
+      if (up.webRoot === cwd) return { ...up, projectRoot: dir };
+      break;
+    }
+  }
   if (forced !== "web") {
     const here = detectHybrid(cwd); // run from the project root
     if (here) return { type: forced ?? here.type, projectRoot: cwd, webRoot: here.webRoot };
@@ -127,8 +187,9 @@ function resolveProject(cwd) {
   return { type: forced ?? "web", projectRoot: cwd, webRoot: cwd };
 }
 
-const { type, projectRoot, webRoot } = resolveProject(process.cwd());
-const isHybrid = type !== "web";
+const { type, projectRoot, webRoot, bundler } = resolveProject(process.cwd());
+const isElectron = type === "electron";
+const isHybrid = type === "cordova" || type === "capacitor";
 const rel = (p) => path.relative(projectRoot, p) || ".";
 
 function copyDir(src, dest) {
@@ -241,7 +302,10 @@ function copyTemplateProject(src, dest, root = dest) {
 
 // Creates the template's package.json, or merges its dependencies and scripts
 // into an existing one: existing entries (e.g. an installed jops-core) are kept.
-function mergeTemplatePackageJson(templatePath, targetPath) {
+// Next.js template: removes "type": "commonjs". Electron template: removes
+// "type": "module" (the main process uses require), sets "main" and keeps
+// jops-core in devDependencies (the app uses the vendored copy).
+function mergeTemplatePackageJson(templatePath, targetPath, electron = false) {
   const template = JSON.parse(fs.readFileSync(templatePath, "utf8"));
   if (!fs.existsSync(targetPath)) {
     fs.writeFileSync(targetPath, JSON.stringify(template, null, 2) + "\n", "utf8");
@@ -252,10 +316,20 @@ function mergeTemplatePackageJson(templatePath, targetPath) {
   pkg.private ??= true;
   // `npm init -y` writes "type": "commonjs", which makes Next.js (Turbopack)
   // reject the project's ES module sources; Next.js projects have no "type".
-  if (pkg.type === "commonjs") {
+  if (!electron && pkg.type === "commonjs") {
     delete pkg.type;
     console.log('[jops-core] Removed "type": "commonjs" from package.json (Next.js uses ES modules)');
   }
+  if (electron) {
+    if (pkg.type === "module") {
+      delete pkg.type;
+      console.log('[jops-core] Removed "type": "module" from package.json (the Electron main process uses require)');
+    }
+    pkg.main = template.main;
+    if (moveToDevDependencies(pkg, "jops-core")) {
+      console.log("[jops-core] Moved jops-core to devDependencies (the app uses the vendored copy in src/lib/)");
+    }
+  }
   for (const section of ["dependencies", "devDependencies"]) {
     for (const [name, spec] of Object.entries(template[section] ?? {})) {
       const existing = pkg.dependencies?.[name] ?? pkg.devDependencies?.[name];
@@ -275,7 +349,54 @@ function mergeTemplatePackageJson(templatePath, targetPath) {
     pkg.scripts = { ...pkg.scripts, [name]: command };
   }
   fs.writeFileSync(targetPath, JSON.stringify(pkg, null, 2) + "\n", "utf8");
-  console.log("[jops-core] Added the Next.js dependencies and scripts to package.json");
+  console.log(`[jops-core] Added the ${electron ? "Electron" : "Next.js"} dependencies and scripts to package.json`);
+}
+
+// Moves a package from dependencies to devDependencies. Returns true when moved.
+function moveToDevDependencies(pkg, name) {
+  const spec = pkg.dependencies?.[name];
+  if (!spec) return false;
+  delete pkg.dependencies[name];
+  if (!Object.keys(pkg.dependencies).length) delete pkg.dependencies;
+  pkg.devDependencies = { ...pkg.devDependencies, [name]: pkg.devDependencies?.[name] ?? spec };
+  return true;
+}
+
+// ─── Electron helpers ────────────────────────────────────────────────────────
+
+// CSP of an Electron page: only the app's own files, plus inline scripts (the
+// import map, and the on* attributes that bindEvents() wires) and blob: workers
+// (Thread). Remote scripts and eval stay blocked.
+const ELECTRON_CSP =
+  "default-src 'self'; script-src 'self' 'unsafe-inline' blob:; style-src 'self' 'unsafe-inline'; img-src 'self' data:";
+
+// Copies the contents of a web template's src/ (and its assets/) flat into the
+// Electron web folder, rewriting root-based paths (/src/x, ./src/x, /assets/x)
+// to page-relative ones (x, assets/x): under file:// a leading / is the disk root.
+function copyElectronTemplate(templateDir, dest) {
+  const rewrite = (text) => text
+    .replace(/(["'`(])\.?\/src\//g, "$1")
+    .replace(/(["'`(])\.?\/assets\//g, "$1assets/");
+  const copy = (src, to) => {
+    fs.mkdirSync(to, { recursive: true });
+    for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+      if (entry.name === ".DS_Store" || entry.name.endsWith(".md")) continue;
+      const srcPath = path.join(src, entry.name);
+      const destPath = path.join(to, entry.name);
+      if (entry.isDirectory()) copy(srcPath, destPath);
+      else if (fs.existsSync(destPath)) console.log(`[jops-core] Kept the existing ${rel(destPath)}`);
+      else {
+        if ([".js", ".html", ".css"].includes(path.extname(entry.name))) {
+          fs.writeFileSync(destPath, rewrite(fs.readFileSync(srcPath, "utf8")), "utf8");
+        } else {
+          fs.copyFileSync(srcPath, destPath);
+        }
+        console.log(`[jops-core] Created ${rel(destPath)}`);
+      }
+    }
+  };
+  copy(path.join(templateDir, "src"), dest);
+  if (fs.existsSync(path.join(templateDir, "assets"))) copy(path.join(templateDir, "assets"), path.join(dest, "assets"));
 }
 
 // ─── template selection ──────────────────────────────────────────────────────
@@ -289,8 +410,9 @@ async function askTemplate() {
     "  1. Empty JOPS project (basic skeleton for JOPS project architecture)\n" +
     "  2. Hello World JOPS project (an example project utilizing all features)\n" +
     "  3. Next.js JOPS Embedded SPA (a Next.js project hosting a JOPS SPA)\n" +
-    "  4. None (I'll create my own architecture)\n" +
-    "Enter choice (1-4): ",
+    "  4. Electron JOPS Desktop App (an Electron Forge project with a JOPS SPA)\n" +
+    "  5. None (I'll create my own architecture)\n" +
+    "Enter choice (1-5): ",
     resolve,
   ));
   rl.close();
@@ -368,8 +490,8 @@ if (command === "init" && choice === "3") {
     "tsconfig.json", "src/app", "public/jops-spa", "data/quotes.json",
   ].filter((p) => fs.existsSync(path.join(cwd, p)));
 
-  if (isHybrid) {
-    console.error(`[jops-core] This is a ${type} project; create the Next.js project in another folder.`);
+  if (isHybrid || isElectron) {
+    console.error(`[jops-core] This is ${isElectron ? "an Electron" : `a ${type}`} project; create the Next.js project in another folder.`);
     process.exitCode = 1;
   } else if (conflicts.length) {
     console.error(`[jops-core] This folder already has ${conflicts.join(", ")}. Nothing was changed.`);
@@ -401,6 +523,161 @@ if (command === "init" && choice === "3") {
   }
 }
 
+// ─── init: Electron JOPS Desktop App (template 4) ─────────────────────────────
+
+if (command === "init" && choice === "4") {
+  const cwd = process.cwd();
+  const templateDir = path.join(__dirname, "../templates/electron-jops-app");
+  const existing = readPackageJson(cwd);
+  // Paths that would clash with an existing project: nothing is written then.
+  const conflicts = [
+    "forge.config.js", "forge.config.cjs", "forge.config.mjs", "forge.config.ts",
+    "src/main.js", "src/index.html", "src/App.js",
+  ].filter((p) => fs.existsSync(path.join(cwd, p)));
+  const mainFile = existing?.main && path.resolve(cwd, existing.main);
+  if (mainFile && mainFile !== path.join(cwd, "src", "main.js") && fs.existsSync(mainFile)) {
+    conflicts.push(`"main": "${existing.main}"`);
+  }
+
+  if (isHybrid) {
+    console.error(`[jops-core] This is a ${type} project; create the Electron project in another folder.`);
+    process.exitCode = 1;
+  } else if (conflicts.length) {
+    console.error(`[jops-core] This folder already has ${conflicts.join(", ")}. Nothing was changed.`);
+    console.error("            Run init in an empty folder (or a fresh npm project) to create the Electron project.");
+    if (isElectron) console.error("            To add JOPS to this Electron project, run init again and choose 1, 2 or 5.");
+    process.exitCode = 1;
+  } else {
+    copyTemplateProject(templateDir, cwd);
+    mergeTemplatePackageJson(path.join(templateDir, "package.json"), path.join(cwd, "package.json"), true);
+    console.log("[jops-core] Created the Electron JOPS Desktop App project in this folder.");
+
+    const libDir = path.join(cwd, "src", "lib");
+    fs.mkdirSync(libDir, { recursive: true });
+    fs.copyFileSync(path.join(__dirname, "../lib/jops-core.min.js"), path.join(libDir, "jops-core.min.js"));
+    console.log("[jops-core] Vendored jops-core.min.js → src/lib/jops-core.min.js");
+
+    console.log("[jops-core] Installing dependencies (npm install)…");
+    const install = spawnSync("npm", ["install"], {
+      cwd,
+      stdio: "inherit",
+      shell: process.platform === "win32",
+    });
+    if (install.status !== 0) {
+      console.warn("[jops-core] npm install did not complete. Run it yourself: npm install");
+    }
+    console.log("");
+    console.log("[jops-core] Next steps:");
+    console.log("            npm start          run the app");
+    console.log("            npm run make       package it (out/make/)");
+    console.log("            Paths JOPS resolves are page-relative (layout/x.html, not ./ or /): the page is loaded from file://");
+  }
+}
+
+// ─── init: existing Electron project (templates 1, 2 and none) ───────────────
+// The library goes into the web folder (lib/), index.html gets an import map,
+// the module script and a CSP (ELECTRON_CSP), and the web
+// templates are copied flat into the web folder with page-relative paths.
+
+const FORGE_SAMPLE_MARK = "Welcome to your Electron application";
+
+if (command === "init" && !wpMode && isElectron && choice !== "3" && choice !== "4") {
+  const indexPath = path.join(webRoot, "index.html");
+  const template = choice === "1" ? "empty" : choice === "2" ? "hello-world" : null;
+
+  if (bundler) {
+    console.error("[jops-core] This Electron project builds its page with a bundler (Forge vite/webpack template).");
+    console.error("            JOPS loads its files as they are: use Forge's default template");
+    console.error("            (npx create-electron-app@latest my-app), or run `npx jops-core init` in an empty");
+    console.error("            folder and choose 4 (Electron JOPS Desktop App).");
+    process.exitCode = 1;
+  } else if (template && fs.existsSync(path.join(webRoot, "App.js"))) {
+    console.error(`[jops-core] ${rel(path.join(webRoot, "App.js"))} already exists. Nothing was changed.`);
+    process.exitCode = 1;
+  } else {
+    console.log(`[jops-core] ${forced ? "Using" : "Detected"} Electron project → web folder: ${rel(webRoot)}/`);
+    fs.mkdirSync(path.join(webRoot, "lib"), { recursive: true });
+    fs.copyFileSync(path.join(__dirname, "../lib/jops-core.min.js"), path.join(webRoot, "lib", "jops-core.min.js"));
+    console.log(`[jops-core] Vendored jops-core.min.js → ${rel(path.join(webRoot, "lib", "jops-core.min.js"))}`);
+
+    const IMPORTMAP = `<script type="importmap">
+      { "imports": { "jops-core": "./lib/jops-core.min.js" } }
+    </script>`;
+    const MODULE_SCRIPT = `<script type="module" src="lib/jops-core.min.js" data-app="App.js"></script>`;
+    const PAGE = `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta http-equiv="Content-Security-Policy" content="${ELECTRON_CSP}" />
+    <title>JOPS App</title>
+    ${IMPORTMAP}
+  </head>
+  <body>
+    ${MODULE_SCRIPT}
+  </body>
+</html>
+`;
+
+    const isSample = fs.existsSync(indexPath) && fs.readFileSync(indexPath, "utf8").includes(FORGE_SAMPLE_MARK);
+    if (isSample) {
+      let backup = path.join(webRoot, "index.forge.html");
+      for (let n = 1; fs.existsSync(backup); n++) backup = path.join(webRoot, `index.forge-${n}.html`);
+      fs.renameSync(indexPath, backup);
+      console.log(`[jops-core] Moved Forge's sample page to ${rel(backup)} (its index.css is no longer used).`);
+    }
+    if (!fs.existsSync(indexPath)) {
+      fs.writeFileSync(indexPath, PAGE, "utf8");
+      console.log(`[jops-core] Created ${rel(indexPath)} with a CSP, the import map and the module script.`);
+    } else {
+      let html = fs.readFileSync(indexPath, "utf8");
+      const original = html;
+      if (!(/type=["']importmap["']/.test(html) && html.includes('"jops-core"'))) {
+        html = html.replace("</head>", `  ${IMPORTMAP}\n  </head>`);
+        console.log(`[jops-core] Added the import map to ${rel(indexPath)}.`);
+      }
+      if (!/src=["'][^"']*jops-core\.min\.js["']/.test(html)) {
+        html = html.replace("</body>", `  ${MODULE_SCRIPT}\n  </body>`);
+        console.log(`[jops-core] Added the module script to ${rel(indexPath)}.`);
+      }
+      const allowed = allowJopsScripts(html);
+      if (allowed !== html) {
+        html = allowed;
+        console.log("[jops-core] Content-Security-Policy: allowed the inline importmap ('unsafe-inline') and Thread workers (blob:).");
+      } else if (!/http-equiv=["']Content-Security-Policy["']/i.test(html)) {
+        console.log("[jops-core] Note: the page has no Content-Security-Policy; Electron warns about that. See the README (Electron).");
+      }
+      if (html !== original) fs.writeFileSync(indexPath, html, "utf8");
+      else console.log(`[jops-core] ${rel(indexPath)} already configured.`);
+    }
+
+    writeVscodeSettings();
+
+    const pkgPath = path.join(projectRoot, "package.json");
+    if (fs.existsSync(pkgPath)) {
+      const p = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+      let changed = false;
+      if (moveToDevDependencies(p, "jops-core")) {
+        changed = true;
+        console.log(`[jops-core] Moved jops-core to devDependencies (the app uses the vendored copy in ${rel(path.join(webRoot, "lib"))}/).`);
+      }
+      if (!p.scripts?.["jops:update"]) {
+        p.scripts = { ...p.scripts, "jops:update": "jops-core update" };
+        changed = true;
+        console.log('[jops-core] Added "jops:update" script to package.json.');
+      }
+      if (changed) fs.writeFileSync(pkgPath, JSON.stringify(p, null, 2) + "\n", "utf8");
+    }
+
+    if (template) {
+      copyElectronTemplate(path.join(__dirname, "../templates", template), webRoot);
+      console.log(`[jops-core] Created ${template === "empty" ? "empty JOPS project skeleton" : "Hello World JOPS project"} in ${rel(webRoot)}/.`);
+    } else {
+      console.log(`[jops-core] No template applied. Create ${rel(path.join(webRoot, "App.js"))} (data-app="App.js").`);
+    }
+    console.log("[jops-core] Paths JOPS resolves are page-relative (layout/x.html, not ./ or /): the page is loaded from file://");
+  }
+}
+
 // ─── index.html helpers (hybrid projects) ────────────────────────────────────
 
 // Same policy as Cordova's default, plus 'unsafe-inline' for the inline import map
@@ -498,9 +775,50 @@ function schemeWarnings(xml) {
   return warnings;
 }
 
+// VS Code: lit-html extension recommendation and settings, in the project root.
+function writeVscodeSettings() {
+  const vscodeSettingsDir = path.join(projectRoot, ".vscode");
+  if (!fs.existsSync(vscodeSettingsDir)) fs.mkdirSync(vscodeSettingsDir);
+
+  const extensionsJsonPath = path.join(vscodeSettingsDir, "extensions.json");
+  const extensionsJson = fs.existsSync(extensionsJsonPath)
+    ? JSON.parse(fs.readFileSync(extensionsJsonPath, "utf8"))
+    : { recommendations: [] };
+  if (!extensionsJson.recommendations.includes("bierner.lit-html")) {
+    extensionsJson.recommendations.push("bierner.lit-html");
+    fs.writeFileSync(extensionsJsonPath, JSON.stringify(extensionsJson, null, 2) + "\n", "utf8");
+  }
+
+  const settingsJsonPath = path.join(vscodeSettingsDir, "settings.json");
+  const settingsJson = fs.existsSync(settingsJsonPath)
+    ? JSON.parse(fs.readFileSync(settingsJsonPath, "utf8"))
+    : {};
+  if (!settingsJson["lit-html.tags"]?.includes("layout")) {
+    settingsJson["lit-html.tags"] = [...(settingsJson["lit-html.tags"] ?? []), "layout"];
+  }
+  const jopsTagColor = "#569CD6";
+  const rules = settingsJson["editor.tokenColorCustomizations"]?.textMateRules ?? [];
+  const hasRule = rules.some(r => r.scope === "invalid.illegal.unrecognized-tag.html");
+  if (!hasRule) {
+    settingsJson["editor.tokenColorCustomizations"] = {
+      ...settingsJson["editor.tokenColorCustomizations"],
+      textMateRules: [
+        ...rules,
+        {
+          scope: "invalid.illegal.unrecognized-tag.html",
+          settings: { foreground: jopsTagColor }
+        }
+      ]
+    };
+  }
+  fs.writeFileSync(settingsJsonPath, JSON.stringify(settingsJson, null, 2) + "\n", "utf8");
+
+  console.log("[jops-core] VS Code: install the recommended 'lit-html' extension (bierner.lit-html) for HTML highlighting inside layout`` template literals.");
+}
+
 // ─── init ────────────────────────────────────────────────────────────────────
 
-if (command === "init" && !wpMode && choice !== "3") {
+if (command === "init" && !wpMode && !isElectron && choice !== "3" && choice !== "4") {
   fs.mkdirSync(webRoot, { recursive: true });
   if (isHybrid) {
     console.log(`[jops-core] ${forced ? "Using" : "Detected"} ${type} project → web folder: ${rel(webRoot)}/`);
@@ -606,43 +924,7 @@ ${cordovaBody}${MODULE_SCRIPT}
   }
 
   // VS Code extension recommendation (project root, so it is never bundled into a hybrid app)
-  const vscodeSettingsDir = path.join(projectRoot, ".vscode");
-  if (!fs.existsSync(vscodeSettingsDir)) fs.mkdirSync(vscodeSettingsDir);
-
-  const extensionsJsonPath = path.join(vscodeSettingsDir, "extensions.json");
-  const extensionsJson = fs.existsSync(extensionsJsonPath)
-    ? JSON.parse(fs.readFileSync(extensionsJsonPath, "utf8"))
-    : { recommendations: [] };
-  if (!extensionsJson.recommendations.includes("bierner.lit-html")) {
-    extensionsJson.recommendations.push("bierner.lit-html");
-    fs.writeFileSync(extensionsJsonPath, JSON.stringify(extensionsJson, null, 2) + "\n", "utf8");
-  }
-
-  const settingsJsonPath = path.join(vscodeSettingsDir, "settings.json");
-  const settingsJson = fs.existsSync(settingsJsonPath)
-    ? JSON.parse(fs.readFileSync(settingsJsonPath, "utf8"))
-    : {};
-  if (!settingsJson["lit-html.tags"]?.includes("layout")) {
-    settingsJson["lit-html.tags"] = [...(settingsJson["lit-html.tags"] ?? []), "layout"];
-  }
-  const jopsTagColor = "#569CD6";
-  const rules = settingsJson["editor.tokenColorCustomizations"]?.textMateRules ?? [];
-  const hasRule = rules.some(r => r.scope === "invalid.illegal.unrecognized-tag.html");
-  if (!hasRule) {
-    settingsJson["editor.tokenColorCustomizations"] = {
-      ...settingsJson["editor.tokenColorCustomizations"],
-      textMateRules: [
-        ...rules,
-        {
-          scope: "invalid.illegal.unrecognized-tag.html",
-          settings: { foreground: jopsTagColor }
-        }
-      ]
-    };
-  }
-  fs.writeFileSync(settingsJsonPath, JSON.stringify(settingsJson, null, 2) + "\n", "utf8");
-
-  console.log("[jops-core] VS Code: install the recommended 'lit-html' extension (bierner.lit-html) for HTML highlighting inside layout`` template literals.");
+  writeVscodeSettings();
 
   // Inject scripts into consumer's package.json
   const pkgPath = path.join(projectRoot, "package.json");
@@ -719,8 +1001,11 @@ if (command === "update") {
 }
 
 if (command === "update") {
-  // A Next.js project serves the library from public/lib/.
-  const libRoot = type === "web" && isNextProject(projectRoot) ? path.join(projectRoot, "public") : webRoot;
+  // A Next.js project serves the library from public/lib/. An Electron project
+  // vendors it into its web folder (src/lib/), or into the project's lib/ when set up by hand.
+  const libRoot = type === "web" && isNextProject(projectRoot) ? path.join(projectRoot, "public")
+    : isElectron && !fs.existsSync(path.join(webRoot, "lib")) && fs.existsSync(path.join(projectRoot, "lib")) ? projectRoot
+    : webRoot;
   const libDir = path.join(libRoot, "lib");
   const vendorDest = path.join(libDir, "jops-core.min.js");
   const vendorSrc = path.join(__dirname, "../lib/jops-core.min.js");
@@ -734,6 +1019,7 @@ if (command === "update") {
     fs.copyFileSync(vendorSrc, vendorDest);
     console.log(`[jops-core] Updated ${rel(vendorDest)} to v${pkg.version}`);
   }
+
 }
 
 // ─── build ───────────────────────────────────────────────────────────────────
@@ -744,6 +1030,10 @@ if (command === "build") {
     console.log(`[jops-core] Not needed in a ${type} project — ${rel(webRoot)}/ is shipped as-is. Use \`${native}\`.`);
     process.exit(0);
   }
+  if (isElectron) {
+    console.log(`[jops-core] Not needed in an Electron project — ${rel(webRoot)}/ is packaged as-is. Use \`npm run make\`.`);
+    process.exit(0);
+  }
 
   const BUILD_EXCLUDE = new Set([
     "node_modules", "dist", ".git",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jops-core",
-  "version": "1.1.4",
+  "version": "1.1.6",
   "description": "A no-bundler, OOP-first SPA framework with Android-style view composition",
   "type": "module",
   "exports": {
@@ -68,7 +68,9 @@
     "next-js",
     "next.js",
     "ssr",
-    "wordpress"
+    "wordpress",
+    "electron",
+    "desktop"
   ],
   "author": "arik@ui-db.com",
   "license": "MIT",

package/templates/electron-jops-app/README.md

@@ -0,0 +1,27 @@
+# Electron JOPS Desktop App
+
+An [Electron](https://www.electronjs.org/) desktop app whose UI is a [JOPS](https://github.com/uidb-dev/jops-core) SPA. Created with `npx jops-core init` (choice 4).
+
+```bash
+npm start          # run the app
+npm run make       # package it (out/make/)
+npm run jops:update  # after upgrading jops-core: copy the new library to src/lib/
+```
+
+## Structure
+
+| Path | Process | Role |
+|---|---|---|
+| `src/main.js` | main | creates the window, answers IPC calls (`app:info`, `files:list`) |
+| `src/preload.js` | preload | exposes only named functions to the page as `window.api.*` (`contextBridge`) |
+| `src/index.html` | renderer | CSP, import map, the jops-core script (`data-app="App.js"`) |
+| `src/App.js`, `src/layout/main.html` | renderer | root view: sidebar and `<Router jops screens>` |
+| `src/HomeView.js`, `src/FilesView.js` | renderer | the two screens; both call `window.api` |
+| `src/lib/jops-core.min.js` | renderer | the vendored library (jops-core itself is a devDependency) |
+
+## Rules
+
+- **Paths:** the page is loaded from `file://`, so every path JOPS resolves (`data-app`, `src=`, `layout=`, `loadLayout()`, `setStyle()`) is page-relative, with no leading `./` or `/`: `layout/main.html`, not `/layout/main.html` (that would be the disk root). The import map value is a URL and keeps its `./`.
+- **Calling the main process:** add an `ipcMain.handle("name", …)` in `main.js`, expose it in `preload.js`, call `await window.api.name()` from a view. Validate arguments in the main process.
+- **Events from the main process:** expose `onX(callback)` in the preload (`ipcRenderer.on`) returning an unsubscribe function, subscribe in `onResume()` and unsubscribe in `onPause()` or `destroy()`, or forward the data into an owned `EventBus` subscription (`EventBus.subscribe(this, …)`).
+- **CSP** (`src/index.html`): only the app's own files load; inline scripts are allowed for the import map and the `on*` attributes JOPS binds, `blob:` for `Thread` workers. Add a host to `connect-src` (e.g. `connect-src 'self' https://api.example.com`) before calling a remote API.

package/templates/electron-jops-app/forge.config.js

@@ -0,0 +1,28 @@
+const { FusesPlugin } = require("@electron-forge/plugin-fuses");
+const { FuseV1Options, FuseVersion } = require("@electron/fuses");
+
+module.exports = {
+  packagerConfig: {
+    asar: true,
+  },
+  rebuildConfig: {},
+  makers: [
+    { name: "@electron-forge/maker-squirrel", config: {} },
+    { name: "@electron-forge/maker-zip", platforms: ["darwin", "win32"] },
+    { name: "@electron-forge/maker-deb", config: {} },
+    { name: "@electron-forge/maker-rpm", config: {} },
+  ],
+  plugins: [
+    { name: "@electron-forge/plugin-auto-unpack-natives", config: {} },
+    // Fuses enable/disable Electron features at package time, before code signing.
+    new FusesPlugin({
+      version: FuseVersion.V1,
+      [FuseV1Options.RunAsNode]: false,
+      [FuseV1Options.EnableCookieEncryption]: true,
+      [FuseV1Options.EnableNodeOptionsEnvironmentVariable]: false,
+      [FuseV1Options.EnableNodeCliInspectArguments]: false,
+      [FuseV1Options.EnableEmbeddedAsarIntegrityValidation]: true,
+      [FuseV1Options.OnlyLoadAppFromAsar]: true,
+    }),
+  ],
+};

package/templates/electron-jops-app/gitignore

@@ -0,0 +1,13 @@
+# dependencies
+node_modules/
+
+# Electron Forge output
+out/
+
+# logs
+*.log
+npm-debug.log*
+
+# misc
+.DS_Store
+.env*

package/templates/electron-jops-app/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "electron-jops-app",
+  "productName": "electron-jops-app",
+  "version": "1.0.0",
+  "private": true,
+  "description": "An Electron desktop app with a JOPS SPA",
+  "main": "src/main.js",
+  "scripts": {
+    "start": "electron-forge start",
+    "package": "electron-forge package",
+    "make": "electron-forge make",
+    "jops:update": "jops-core update"
+  },
+  "dependencies": {
+    "electron-squirrel-startup": "^1.0.1"
+  },
+  "devDependencies": {
+    "@electron-forge/cli": "^8.0.1",
+    "@electron-forge/maker-deb": "^8.0.1",
+    "@electron-forge/maker-rpm": "^8.0.1",
+    "@electron-forge/maker-squirrel": "^8.0.1",
+    "@electron-forge/maker-zip": "^8.0.1",
+    "@electron-forge/plugin-auto-unpack-natives": "^8.0.1",
+    "@electron-forge/plugin-fuses": "^8.0.1",
+    "@electron/fuses": "^2.1.3",
+    "electron": "45.0.0",
+    "jops-core": "^1.1.6"
+  }
+}

package/templates/electron-jops-app/src/App.js

@@ -0,0 +1,24 @@
+import { View } from "jops-core";
+
+// The root view renders layout/main.html into <body>.
+// Paths are page-relative (no leading ./ or /): the page is loaded from file://.
+export default class App {
+  constructor() {
+    const main = new View();
+    main
+      .loadLayout("layout/main.html")
+      .then(() => main.render())
+      .then(() => {
+        markCurrentLink();
+        window.addEventListener("hashchange", markCurrentLink);
+      });
+  }
+}
+
+// Highlights the sidebar link of the current route (#home, #files?…).
+function markCurrentLink() {
+  const route = location.hash.split("?")[0];
+  for (const link of document.querySelectorAll(".nav-link")) {
+    link.classList.toggle("active", link.getAttribute("href") === route);
+  }
+}

package/templates/electron-jops-app/src/FilesView.js

@@ -0,0 +1,48 @@
+import { View, layout } from "jops-core";
+
+// Files screen: lists the folder the app was started from (window.api.listFiles()),
+// one FileRow sub-view per entry.
+export default class FilesView extends View {
+  onResume() {
+    this.showFiles(); // refreshed every time the screen comes to the front
+  }
+
+  async showFiles() {
+    if (!window.api) return this.showMessage("Desktop app only: run it with npm start.");
+    try {
+      const { dir, entries } = await window.api.listFiles();
+      this.get("files_dir").set(layout`${dir}`);
+      this.removeSubViews();
+      this.get("files_list").set("");
+      if (entries.length === 0) return this.showMessage("This folder is empty.");
+      for (const entry of entries) this.addSubView("files_list", new FileRow(entry));
+    } catch (error) {
+      this.showMessage(`Could not list the folder: ${error.message}`);
+    }
+  }
+
+  // One row across the table (empty folder, error).
+  showMessage(text) {
+    this.removeSubViews();
+    this.get("files_list").set(layout`<tr><td colspan="3" class="muted">${text}</td></tr>`);
+  }
+}
+
+class FileRow extends View {
+  constructor(entry) {
+    super();
+    this.layout = layout`
+      <tr>
+        <td>${entry.name}</td>
+        <td class="muted">${entry.folder ? "Folder" : "File"}</td>
+        <td class="num muted">${entry.folder ? "" : formatSize(entry.size)}</td>
+      </tr>`;
+    this.inflate();
+  }
+}
+
+function formatSize(bytes) {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+}

package/templates/electron-jops-app/src/HomeView.js

@@ -0,0 +1,20 @@
+import { View, layout } from "jops-core";
+
+// Home screen: shows what the main process reports through window.api.appInfo().
+export default class HomeView extends View {
+  async onLayout() {
+    if (!window.api) {
+      this.get("app_info").set(layout`<dt>Desktop app only</dt><dd>Run it with npm start.</dd>`);
+      return;
+    }
+    const info = await window.api.appInfo();
+    const rows = [
+      ["App", `${info.name} ${info.version}`],
+      ["Electron", info.electron],
+      ["Chrome", info.chrome],
+      ["Node.js", info.node],
+      ["Platform", info.platform],
+    ];
+    this.get("app_info").set(rows.map(([name, value]) => layout`<dt>${name}</dt><dd>${value}</dd>`).join(""));
+  }
+}

package/templates/electron-jops-app/src/index.css

@@ -0,0 +1,151 @@
+:root {
+  --bg: #f5f6f8;
+  --sidebar-bg: #eceef2;
+  --surface: #ffffff;
+  --border: #e1e4ea;
+  --text: #1d2330;
+  --text-muted: #6b7385;
+  --accent: #3b6ef5;
+  --hover: rgba(0, 0, 0, 0.05);
+  color-scheme: light dark;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --bg: #17191e;
+    --sidebar-bg: #1f2228;
+    --surface: #23262d;
+    --border: #33373f;
+    --text: #e7e9ee;
+    --text-muted: #9097a5;
+    --accent: #5b86ff;
+    --hover: rgba(255, 255, 255, 0.06);
+  }
+}
+
+* {
+  box-sizing: border-box;
+}
+
+html,
+body {
+  height: 100%;
+  margin: 0;
+}
+
+body {
+  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+  font-size: 14px;
+  color: var(--text);
+  background: var(--bg);
+  overflow: hidden;
+}
+
+/* App shell: fixed sidebar, the Router fills the rest of the window */
+.app {
+  display: flex;
+  height: 100vh;
+}
+
+.sidebar {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  width: 200px;
+  padding: 16px 10px;
+  background: var(--sidebar-bg);
+  border-right: 1px solid var(--border);
+  user-select: none;
+}
+
+.brand {
+  padding: 4px 10px 14px;
+  font-weight: 600;
+}
+
+.nav-link {
+  padding: 7px 10px;
+  border-radius: 6px;
+  color: var(--text);
+  text-decoration: none;
+}
+
+.nav-link:hover {
+  background: var(--hover);
+}
+
+.nav-link.active {
+  background: var(--hover);
+  font-weight: 600;
+}
+
+/* <Router jops screens class="content">: each route is a .jops-screen that fills
+   the router and scrolls on its own. */
+.content {
+  flex: 1;
+  min-width: 0;
+  --jops-screen-bg: var(--bg);
+}
+
+.page {
+  max-width: 760px;
+  padding: 24px 28px 32px;
+}
+
+h1 {
+  margin: 0 0 4px;
+  font-size: 20px;
+}
+
+.muted {
+  color: var(--text-muted);
+}
+
+.card {
+  margin-top: 16px;
+  background: var(--surface);
+  border: 1px solid var(--border);
+  border-radius: 10px;
+}
+
+.info {
+  display: grid;
+  grid-template-columns: max-content 1fr;
+  gap: 8px 24px;
+  padding: 16px 20px;
+}
+
+.info dt {
+  color: var(--text-muted);
+}
+
+.info dd {
+  margin: 0;
+}
+
+.table {
+  width: 100%;
+  border-collapse: separate;
+  border-spacing: 0;
+  overflow: hidden;
+}
+
+.table th,
+.table td {
+  padding: 8px 14px;
+  text-align: left;
+  border-bottom: 1px solid var(--border);
+}
+
+.table tr:last-child td {
+  border-bottom: none;
+}
+
+.table th {
+  font-weight: 600;
+  color: var(--text-muted);
+}
+
+.table .num {
+  text-align: right;
+}

package/templates/electron-jops-app/src/index.html

@@ -0,0 +1,20 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <!-- Only the app's own files; 'unsafe-inline' for the import map and the on*
+         attributes that JOPS binds, blob: for Thread workers. -->
+    <meta
+      http-equiv="Content-Security-Policy"
+      content="default-src 'self'; script-src 'self' 'unsafe-inline' blob:; style-src 'self' 'unsafe-inline'; img-src 'self' data:"
+    />
+    <title>Electron JOPS App</title>
+    <script type="importmap">
+      { "imports": { "jops-core": "./lib/jops-core.min.js" } }
+    </script>
+    <link rel="stylesheet" href="index.css" />
+  </head>
+  <body>
+    <script type="module" src="lib/jops-core.min.js" data-app="App.js"></script>
+  </body>
+</html>

package/templates/electron-jops-app/src/layout/files_view.html

@@ -0,0 +1,12 @@
+<section class="page">
+  <h1>Files</h1>
+  <p id="files_dir" class="muted"></p>
+  <table class="card table">
+    <thead>
+      <tr><th>Name</th><th>Type</th><th class="num">Size</th></tr>
+    </thead>
+    <tbody id="files_list">
+      <tr><td colspan="3" class="muted">Loading…</td></tr>
+    </tbody>
+  </table>
+</section>

package/templates/electron-jops-app/src/layout/home_view.html

@@ -0,0 +1,7 @@
+<section class="page">
+  <h1>Welcome</h1>
+  <p class="muted">A JOPS SPA running as the UI of an Electron app.</p>
+  <dl id="app_info" class="card info">
+    <dt>Loading…</dt>
+  </dl>
+</section>

package/templates/electron-jops-app/src/layout/main.html

@@ -0,0 +1,12 @@
+<div class="app">
+  <nav class="sidebar">
+    <div class="brand">JOPS · Electron</div>
+    <a class="nav-link" href="#home">Home</a>
+    <a class="nav-link" href="#files">Files</a>
+  </nav>
+
+  <Router jops screens class="content">
+    <HomeView jops src="HomeView.js" layout="layout/home_view.html" path="/home"></HomeView>
+    <FilesView jops src="FilesView.js" layout="layout/files_view.html" path="/files"></FilesView>
+  </Router>
+</div>

package/templates/electron-jops-app/src/main.js

@@ -0,0 +1,73 @@
+// Electron main process: creates the window and answers the page's IPC calls.
+const { app, BrowserWindow, ipcMain, nativeTheme } = require("electron");
+const path = require("node:path");
+const fs = require("node:fs/promises");
+
+// Windows installer (Squirrel): quit while it creates or removes shortcuts.
+if (require("electron-squirrel-startup")) app.quit();
+
+// ─── IPC handlers (exposed to the page by preload.js) ────────────────────────
+
+// "app:info": versions and platform of the running app.
+function appInfo() {
+  return {
+    name: app.getName(),
+    version: app.getVersion(),
+    electron: process.versions.electron,
+    chrome: process.versions.chrome,
+    node: process.versions.node,
+    platform: `${process.platform} ${process.arch}`,
+  };
+}
+
+// "files:list": the folder the app was started from. fs.readdir works the
+// same on macOS, Windows and Linux. Hidden and unreadable entries are left out.
+async function listFiles() {
+  const dir = process.cwd();
+  const names = (await fs.readdir(dir))
+    .filter((name) => !name.startsWith("."))
+    .sort((a, b) => a.localeCompare(b))
+    .slice(0, 500);
+  const entries = [];
+  for (const name of names) {
+    try {
+      const stats = await fs.stat(path.join(dir, name));
+      entries.push({ name, folder: stats.isDirectory(), size: stats.size });
+    } catch {
+      // Broken symlink or no permission.
+    }
+  }
+  return { dir, entries };
+}
+
+// ─── window ──────────────────────────────────────────────────────────────────
+
+function createWindow() {
+  const win = new BrowserWindow({
+    width: 960,
+    height: 640,
+    // Same as --bg in index.css, so the window is never white before the first paint.
+    backgroundColor: nativeTheme.shouldUseDarkColors ? "#17191e" : "#f5f6f8",
+    // Electron's secure defaults stay on: contextIsolation, sandbox, no nodeIntegration.
+    webPreferences: {
+      preload: path.join(__dirname, "preload.js"),
+    },
+  });
+  // file:// page: every path JOPS resolves is page-relative (no leading ./ or /).
+  win.loadFile(path.join(__dirname, "index.html"));
+}
+
+app.whenReady().then(() => {
+  ipcMain.handle("app:info", appInfo);
+  ipcMain.handle("files:list", listFiles);
+  createWindow();
+  // macOS: re-create the window when the dock icon is clicked.
+  app.on("activate", () => {
+    if (BrowserWindow.getAllWindows().length === 0) createWindow();
+  });
+});
+
+// Quit when all windows are closed, except on macOS.
+app.on("window-all-closed", () => {
+  if (process.platform !== "darwin") app.quit();
+});

package/templates/electron-jops-app/src/preload.js

@@ -0,0 +1,10 @@
+// The bridge between the page and the main process. Only these named
+// functions are exposed to the page, as window.api.*.
+const { contextBridge, ipcRenderer } = require("electron");
+
+contextBridge.exposeInMainWorld("api", {
+  // { name, version, electron, chrome, node, platform }
+  appInfo: () => ipcRenderer.invoke("app:info"),
+  // { dir, entries: [{ name, folder, size }] }
+  listFiles: () => ipcRenderer.invoke("files:list"),
+});