@thunderclap-engine/host-electron 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mandalorian007 / ThunderClap Gaming
+
+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

@@ -1,3 +1,138 @@
-# Temporary Holding Version
+# @thunderclap-engine/host-electron
 
-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.
+The ThunderClap desktop shell. A game's web build runs unchanged inside Electron, and the `Host`
+interface (`@thunderclap-engine/engine/host`) is the only seam between them (D-041, Phase 4). The package
+contains no game nouns. The engine never imports it, and it reaches the engine only through the
+engine's exports map (`pnpm check:boundaries` enforces both).
+
+## Layout
+
+| Path | What it is |
+|---|---|
+| `src/index.ts` | What a game imports: `createElectronHost`, `electronBridge`, `inElectronShell`, `ThunderclapBridge` |
+| `src/renderer.ts` | `createElectronHost()`, which satisfies `Host` over the bridge |
+| `src/bridge.ts` | The bridge type and its IPC channel names, shared by all three sides and importing nothing |
+| `src/preload/preload.ts` | The sandboxed preload that exposes `window.thunderclap`; built to `out/preload.cjs` |
+| `src/main/main.ts` | The main process: window, WebGPU switches, `app://` protocol, network block, IPC; built to `out/main.mjs` |
+| `src/main/policy.ts`, `switches.ts` | The main process's rules as pure, unit-tested functions |
+| `harness/` | A noun-free page: boots WebGPU, clears each frame, publishes `window.__desktop`. It is the default renderer |
+| `e2e/shell.spec.ts` | The Playwright Electron-driver smoke on the built shell |
+| `scripts/build.mjs`, `dev.mjs`, `dist.mjs` | Build `out/`, the dev loop, and packaging |
+| `electron-builder.config.mjs` | Unsigned Windows, macOS and Linux packaging into `dist/desktop/` at the repo root (gitignored) |
+
+## Using it from a game
+
+```ts
+import { createWebHost, setDefaultHost } from '@thunderclap-engine/engine/host';
+import { createElectronHost, inElectronShell } from '@thunderclap-engine/host-electron';
+
+const host = inElectronShell() ? createElectronHost() : createWebHost();
+setDefaultHost(host); // or pass it to createGame / the game's ctx
+host.window?.close(); // a desktop-only Quit entry
+```
+
+A game does this in one boot file with a dynamic import, so its web build never loads this package, and shows Quit only when `host.window` exists. The Last Rune does exactly this.
+
+## The bridge: `window.thunderclap`
+
+The preload runs with `sandbox: true`, `contextIsolation: true` and `nodeIntegration: false`. The page gets no Node, no `require` and no `ipcRenderer`. It gets only these members:
+
+| Member | Main process |
+|---|---|
+| `version` (1), `platform` | Read-only values |
+| `openExternal(url): Promise<boolean>` | `shell.openExternal`, only after `safeExternalHttps` passes: plain `https:`, no credentials, no whitespace. This is the same rule as the engine's `safeExternalUrl` (a unit test keeps them equal) |
+| `copyText(text): Promise<boolean>` | `clipboard.writeText` |
+| `fullscreen.get()`, `set(on)`, `onChange(fn)` | `BrowserWindow` fullscreen; `set` waits (up to 2 s) for macOS's animation |
+| `window.minimize()`, `toggleMaximize()`, `close()`, `setTitle(t)` | The caller's `BrowserWindow` |
+
+Every handler checks that the call came from the main frame of the shell's window on the page's own origin, and it checks every argument's type.
+
+`createElectronHost()` maps the bridge onto `Host`:
+
+- `kind: 'electron'`; `embed` is detected, so it is `top` in the shell.
+- `openExternal` returns `invalid` for a bad URL without calling the bridge. Otherwise it returns `opened` for every activation, because a desktop window has no popup blocker.
+- `copyText` returns `copied` when the bridge succeeds, else `manual`. `clipboardWriteAllowed()` is `true`.
+- `fullscreen.active` is a synchronous getter and kept up to date by the main process's change events.
+- `window` exposes `close`, `minimize`, `toggleMaximize` and `setTitle`. `HostWindow.setTitle?` was added to the engine for it.
+
+## WebGPU switches
+
+These are set with `app.commandLine.appendSwitch` before `ready`, so the build does not depend on what this Electron's Chromium enables by default (`src/main/switches.ts`):
+
+| OS | Switches | Dawn backend |
+|---|---|---|
+| macOS | `--enable-unsafe-webgpu` | Metal |
+| Windows | `--enable-unsafe-webgpu` | D3D12 |
+| Linux | `--enable-unsafe-webgpu`, `--enable-features=Vulkan` | Vulkan |
+
+`enable-unsafe-webgpu` turns WebGPU on where Chromium has not shipped it (Linux) and skips Chromium's WebGPU adapter blocklist. The game is WebGPU-only, so on a blocklisted adapter the alternative is no game at all.
+
+For unpackaged runs only, `TC_GPU_SWITCHES="--a --b=c"` replaces the switches, for example to use SwiftShader on a headless Linux runner.
+
+Electron 45.2.2 (Chromium 156) was verified on macOS arm64: the e2e and the packaged app both reach `gpu: ok` with `bgra8unorm`. Windows and Linux are built in CI but have not been run on hardware yet.
+
+## Storage
+
+Storage is the renderer's `localStorage`: the same backend, probe (`probeStorage`) and save format as the web host. This was a PM call, because the user wants browser-only storage for now.
+
+The shell serves the page from one fixed origin, `app://bundle` (a privileged `standard` and `secure` scheme), so saves stay put across launches and updates. The data lives in Electron's `userData` folder, which is named from the product name (`extraMetadata.productName`). For that reason the scheme, the host and the product name must never change after a release.
+
+There is one instance per `userData` (`requestSingleInstanceLock`), because a second instance would find `localStorage` locked.
+
+**Open question (for the user): a file backend.** A `StorageLike` over a JSON file in `app.getPath('userData')` would make saves visible, easy to back up and independent of Chromium's LevelDB. A design for it:
+
+- Main process: one file per save key under `userData/saves/`, written atomically (write a temp file, then rename). Synchronous reads at start through a preloaded snapshot.
+- Bridge: `storage.snapshot()` once at boot, then `storage.set(key, value)` and `storage.remove(key)` as fire-and-forget IPC.
+- Renderer: an in-memory `StorageLike` seeded from the snapshot and written through. `kind: 'file'`.
+
+The versioning stays `engine/save`'s, unchanged. Moving existing saves would be a one-time copy out of `localStorage` on first launch. Nothing of this is built. Decide before a desktop release whether saves should follow the player outside the app.
+
+## Security and network
+
+- **No network at runtime.** The session cancels every request that is not the page's own origin (`app://bundle`, or the local dev server and its HMR socket in `desktop:dev`), `data:`, `blob:` or `devtools:`. Every `app://` response also carries a CSP with `connect-src 'self'`, `script-src 'self'` and no inline script. Spellcheck is off, so no dictionaries are downloaded.
+- **Local files only.** `app://bundle/<path>` serves files from `out/renderer` (inside the asar), with a path guard (`bundleFile`). Unknown routes fall back to `index.html`.
+- **No new windows, webviews, or navigation away.** A new-window request for a plain https URL from the page itself opens in the system browser through `shell.openExternal`, under the same rule as the bridge. That covers a `target="_blank"` link, such as the engine's link widget on a click or Enter. Every other new-window request is refused. Permission prompts are denied, except HTML fullscreen.
+- **DevTools only when unpackaged.** On macOS the app has a minimal menu (app, edit, window). Elsewhere there is no menu bar.
+- `TC_RENDERER_URL`, `TC_RENDERER_DIR`, `TC_USER_DATA` and `TC_GPU_SWITCHES` are honoured only when unpackaged.
+
+## Scripts
+
+From the repo root:
+
+| Command | What it does |
+|---|---|
+| `pnpm desktop:dev` | Builds main and preload, serves `harness/` with Vite on 127.0.0.1:5199, and opens it in Electron with hot reload. `pnpm desktop:dev --url http://localhost:5173` uses a dev server you already run instead |
+| `pnpm desktop:build` | This package's `dist`: builds `out/` and packages for this OS into `dist/desktop/` at the repo root (gitignored). Flags: `--mac`, `--win`, `--linux`; `--dir` (unpacked only); `--renderer <dir>` (package another built web app, such as a game's `dist/`, instead of the harness; any `dist/desktop/` inside it is skipped) |
+| `pnpm test:e2e:desktop` | Builds `out/` and runs `e2e/shell.spec.ts` with Playwright's Electron driver, a Playwright run of the shell on the desktop harness page |
+| `pnpm check:host-electron` | Typecheck, lint and unit tests (also part of `pnpm check`) |
+
+Electron downloads its binary on first use, not at install. electron-builder downloads its own copy when packaging. Both downloads happen at build time only.
+
+## Packaging
+
+The build is unsigned: no certificate, key or notarisation credential is used or read, and `CSC_IDENTITY_AUTO_DISCOVERY` is forced off.
+
+| OS | Outputs |
+|---|---|
+| macOS | `.dmg` and `.zip` for the host arch. Ad-hoc signed (`identity: '-'`), so Apple silicon runs it. Gatekeeper still warns on first open |
+| Windows | NSIS installer (`.exe`) and `.zip` (x64). Unsigned, so SmartScreen warns |
+| Linux | `.AppImage` and `.tar.gz` (x64) |
+
+The identity defaults to `ThunderClap` / `dev.thunderclap.shell`, with Electron's default icon. A game sets its own identity with these variables:
+
+- `TC_PRODUCT_NAME` and `TC_APP_ID`;
+- `TC_APP_VERSION`;
+- `TC_ICON`: an absolute path to a PNG of at least 512x512. electron-builder makes the `.icns` and `.ico` from it.
+
+Artefacts are named `<product name, spaces as dashes>-<version>-<os>-<arch>.<ext>`.
+
+A game's own repo sets these when it calls `dist` with `--renderer`; this repo only builds the harness shell.
+
+The CI job `desktop` in `.github/workflows/ci.yml` builds the harness shell for all three OSes and uploads the artefacts. It is non-blocking.
+
+## Open questions
+
+- **Code signing and notarisation** (macOS Developer ID, Windows Authenticode). These wait until the user supplies certificates. The config has the hooks, but no material belongs in the repo; it would go in CI secrets.
+- **A file storage backend** (see Storage).
+- **Linux AppImage on Ubuntu 24.04+**, where AppArmor restricts unprivileged user namespaces that Chromium's sandbox uses. It may need `--no-sandbox` or a `.deb` with an AppArmor profile. Not yet tested on a machine.
+- **Auto-update.** There is none, and it would mean a runtime network call. It is out of scope unless the user asks for it.

package/dist/bridge.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The preload bridge: what the Electron shell exposes to the page as `window.thunderclap`
+ * (src/preload/preload.ts), and the IPC channel names behind it. Shared by the main process,
+ * the preload and the renderer, so it imports nothing.
+ *
+ * The page never gets Node, `ipcRenderer` or any Electron module, only these functions. Every
+ * call is checked again in the main process (src/main/ipc.ts): links must be plain `https:`,
+ * text must be a string, and only the shell's own window may call.
+ */
+/** Bumped when a member is removed or changes meaning; adding one does not bump it. */
+export declare const BRIDGE_VERSION = 1;
+/** The global the preload defines. */
+export declare const BRIDGE_GLOBAL = "thunderclap";
+export interface ThunderclapBridge {
+    readonly version: number;
+    /** `process.platform` of the shell: `darwin`, `win32` or `linux`. */
+    readonly platform: string;
+    /**
+     * Opens a plain `https:` URL in the user's browser (`shell.openExternal`). Resolves false
+     * when the main process refused it (not https, credentials, whitespace) or the OS failed.
+     */
+    openExternal(url: string): Promise<boolean>;
+    /** Writes `text` to the system clipboard (`clipboard.writeText`). */
+    copyText(text: string): Promise<boolean>;
+    readonly fullscreen: {
+        /** Whether the window is fullscreen now. */
+        get(): Promise<boolean>;
+        /** Enters or leaves fullscreen; resolves to the state afterwards. */
+        set(on: boolean): Promise<boolean>;
+        /** Calls `fn` whenever the window enters or leaves fullscreen. Returns unsubscribe. */
+        onChange(fn: (on: boolean) => void): () => void;
+    };
+    readonly window: {
+        minimize(): void;
+        toggleMaximize(): void;
+        /** Closes the window; the shell quits when it was the last one. */
+        close(): void;
+        setTitle(title: string): void;
+    };
+}
+/** IPC channels, all prefixed `tc:`. `invoke` channels answer; `send` channels do not. */
+export declare const CH: {
+    readonly openExternal: 'tc:open-external';
+    readonly copyText: 'tc:copy-text';
+    readonly fullscreenGet: 'tc:fullscreen-get';
+    readonly fullscreenSet: 'tc:fullscreen-set';
+    /** main → renderer: the new fullscreen state. */
+    readonly fullscreenChanged: 'tc:fullscreen-changed';
+    readonly minimize: 'tc:window-minimize';
+    readonly toggleMaximize: 'tc:window-toggle-maximize';
+    readonly close: 'tc:window-close';
+    readonly setTitle: 'tc:window-set-title';
+};

package/dist/bridge.js

@@ -0,0 +1,26 @@
+/**
+ * The preload bridge: what the Electron shell exposes to the page as `window.thunderclap`
+ * (src/preload/preload.ts), and the IPC channel names behind it. Shared by the main process,
+ * the preload and the renderer, so it imports nothing.
+ *
+ * The page never gets Node, `ipcRenderer` or any Electron module, only these functions. Every
+ * call is checked again in the main process (src/main/ipc.ts): links must be plain `https:`,
+ * text must be a string, and only the shell's own window may call.
+ */
+/** Bumped when a member is removed or changes meaning; adding one does not bump it. */
+export const BRIDGE_VERSION = 1;
+/** The global the preload defines. */
+export const BRIDGE_GLOBAL = 'thunderclap';
+/** IPC channels, all prefixed `tc:`. `invoke` channels answer; `send` channels do not. */
+export const CH = {
+    openExternal: 'tc:open-external',
+    copyText: 'tc:copy-text',
+    fullscreenGet: 'tc:fullscreen-get',
+    fullscreenSet: 'tc:fullscreen-set',
+    /** main → renderer: the new fullscreen state. */
+    fullscreenChanged: 'tc:fullscreen-changed',
+    minimize: 'tc:window-minimize',
+    toggleMaximize: 'tc:window-toggle-maximize',
+    close: 'tc:window-close',
+    setTitle: 'tc:window-set-title',
+};

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * `@thunderclap-engine/host-electron`, renderer side: what a game imports. The main process and the
+ * preload are built into `out/` by scripts/build.mjs and are not imported by games.
+ */
+export { BRIDGE_VERSION, type ThunderclapBridge } from './bridge.js';
+export { createElectronHost, type ElectronHostOptions, electronBridge, inElectronShell, } from './renderer.js';

package/dist/index.js

@@ -0,0 +1,6 @@
+/**
+ * `@thunderclap-engine/host-electron`, renderer side: what a game imports. The main process and the
+ * preload are built into `out/` by scripts/build.mjs and are not imported by games.
+ */
+export { BRIDGE_VERSION } from './bridge.js';
+export { createElectronHost, electronBridge, inElectronShell, } from './renderer.js';

package/dist/renderer.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The Electron host for the renderer: `Host` (engine/host, D-041) over the preload bridge
+ * `window.thunderclap` (src/bridge.ts). Links and the clipboard go through the main process;
+ * fullscreen and the window controls act on the shell's `BrowserWindow`.
+ *
+ * Storage is the renderer's `localStorage`, the same backend and probe as the web host (PM call,
+ * 2026-11-03: browser storage only for now). The shell serves the page from one fixed origin
+ * (`app://bundle`), so saves stay put across launches and updates. A file backend in `userData`
+ * is an open question; see README.md.
+ */
+import type { Host } from '@thunderclap-engine/engine/host';
+import { type ThunderclapBridge } from './bridge.js';
+export interface ElectronHostOptions {
+    /** The bridge. Default: `window.thunderclap`. Tests pass a fake. */
+    bridge?: ThunderclapBridge;
+    /** The window whose `localStorage` holds saves. Default: the global `window`. */
+    win?: Window;
+}
+/** The preload bridge when this page runs inside the ThunderClap shell, else null. */
+export declare function electronBridge(win?: Window): ThunderclapBridge | null;
+/** True when the page runs inside the ThunderClap Electron shell. */
+export declare function inElectronShell(win?: Window): boolean;
+/**
+ * Builds the Electron host. Throws when there is no bridge (the page is not in the shell);
+ * check `inElectronShell()` first and fall back to `createWebHost()`.
+ */
+export declare function createElectronHost(opts?: ElectronHostOptions): Host;

package/dist/renderer.js

@@ -0,0 +1,102 @@
+import { embedContext, safeExternalUrl } from '@thunderclap-engine/engine/platform';
+import { probeStorage } from '@thunderclap-engine/engine/save';
+import { BRIDGE_GLOBAL } from './bridge.js';
+/** The preload bridge when this page runs inside the ThunderClap shell, else null. */
+export function electronBridge(win = window) {
+    const b = win[BRIDGE_GLOBAL];
+    return b && typeof b.openExternal === 'function' ? b : null;
+}
+/** True when the page runs inside the ThunderClap Electron shell. */
+export function inElectronShell(win = window) {
+    return electronBridge(win) !== null;
+}
+/**
+ * Builds the Electron host. Throws when there is no bridge (the page is not in the shell);
+ * check `inElectronShell()` first and fall back to `createWebHost()`.
+ */
+export function createElectronHost(opts = {}) {
+    const win = opts.win ?? window;
+    const bridge = opts.bridge ?? electronBridge(win);
+    if (!bridge) {
+        throw new Error('createElectronHost: no window.thunderclap bridge (not in the Electron shell)');
+    }
+    const fullscreen = createFullscreen(bridge);
+    return {
+        kind: 'electron',
+        // The shell's window is a Chromium page: frames come from its requestAnimationFrame.
+        requestFrame: (cb) => win.requestAnimationFrame(cb),
+        cancelFrame: (handle) => win.cancelAnimationFrame(handle),
+        embed: embedContext(win),
+        openExternal(url) {
+            // Checked here so a bad link is `invalid` at once, and again in the main process.
+            const href = safeExternalUrl(url);
+            if (!href)
+                return 'invalid';
+            // A desktop window has no popup blocker, so every activation (pad and script too) opens.
+            // The OS answer comes later; a failure there is logged by the main process.
+            void bridge.openExternal(href).catch(() => false);
+            return 'opened';
+        },
+        async copyText(text) {
+            try {
+                return (await bridge.copyText(String(text))) ? 'copied' : 'manual';
+            }
+            catch {
+                return 'manual';
+            }
+        },
+        clipboardWriteAllowed: () => true,
+        fullscreen,
+        storage: {
+            kind: 'local',
+            // The same guarded probe as the web host: null when missing or failing a round trip.
+            open: () => probeStorage(() => win.localStorage),
+        },
+        window: {
+            close: () => bridge.window.close(),
+            minimize: () => bridge.window.minimize(),
+            toggleMaximize: () => bridge.window.toggleMaximize(),
+            setTitle: (title) => bridge.window.setTitle(String(title)),
+        },
+    };
+}
+/**
+ * Fullscreen of the shell's window. `active` is a synchronous getter in `Host`, so the state is kept
+ * here: read once at start, then updated by the main process's change events and by `toggle`.
+ */
+function createFullscreen(bridge) {
+    let on = false;
+    const listeners = new Set();
+    const update = (next) => {
+        if (next === on)
+            return;
+        on = next;
+        for (const fn of [...listeners])
+            fn(on);
+    };
+    bridge.fullscreen.onChange((next) => update(!!next));
+    bridge.fullscreen
+        .get()
+        .then((v) => update(!!v))
+        .catch(() => { });
+    return {
+        available: () => true,
+        get active() {
+            return on;
+        },
+        async toggle() {
+            // `lockLandscape` has no meaning for a desktop window.
+            try {
+                update(!!(await bridge.fullscreen.set(!on)));
+            }
+            catch {
+                // Refused: leave things as they were.
+            }
+            return on;
+        },
+        watch(fn) {
+            listeners.add(fn);
+            return () => listeners.delete(fn);
+        },
+    };
+}

package/out/main.mjs

@@ -0,0 +1,381 @@
+import { readFile } from "node:fs/promises";
+import { dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { BrowserWindow, Menu, app, clipboard, ipcMain, protocol, session, shell } from "electron";
+// packages/host-electron/src/bridge.ts
+/** IPC channels, all prefixed `tc:`. `invoke` channels answer; `send` channels do not. */
+var CH = {
+	openExternal: "tc:open-external",
+	copyText: "tc:copy-text",
+	fullscreenGet: "tc:fullscreen-get",
+	fullscreenSet: "tc:fullscreen-set",
+	/** main → renderer: the new fullscreen state. */
+	fullscreenChanged: "tc:fullscreen-changed",
+	minimize: "tc:window-minimize",
+	toggleMaximize: "tc:window-toggle-maximize",
+	close: "tc:window-close",
+	setTitle: "tc:window-set-title"
+};
+var APP_HOST = "bundle";
+var APP_ORIGIN = `app://${APP_HOST}`;
+/**
+* The main process's copy of the engine's `safeExternalUrl` (platform/links.ts): the URL when
+* it is a plain absolute `https:` link with no credentials and no whitespace, else null. It is
+* checked again here because the bridge can be called with anything.
+*/
+function safeExternalHttps(url) {
+	if (typeof url !== "string") return null;
+	const t = url.trim();
+	if (!t || /\s/.test(t) || !/^https:\/\//i.test(t)) return null;
+	let u;
+	try {
+		u = new URL(t);
+	} catch {
+		return null;
+	}
+	if (u.protocol !== "https:" || !u.hostname || u.username || u.password) return null;
+	return t;
+}
+/**
+* The file under `root` that `app://bundle/<path>` names, or null when the path leaves `root`
+* (`..`, encoded or not) or is malformed. `/` and paths without an extension serve index.html,
+* so a single-page app's routes resolve.
+*/
+function bundleFile(root, requestUrl) {
+	let u;
+	try {
+		u = new URL(requestUrl);
+	} catch {
+		return null;
+	}
+	if (u.protocol !== `app:` || u.host !== "bundle") return null;
+	let path;
+	try {
+		path = decodeURIComponent(u.pathname);
+	} catch {
+		return null;
+	}
+	if (path.includes("\0")) return null;
+	if (path === "/" || path === "" || !extname(path)) path = "/index.html";
+	const base = resolve(root);
+	const file = resolve(base, `.${path}`);
+	const rel = relative(base, file);
+	if (!rel || rel.startsWith(`..${sep}`) || rel === ".." || isAbsolute(rel)) return null;
+	return file;
+}
+var MIME = {
+	".html": "text/html; charset=utf-8",
+	".js": "text/javascript; charset=utf-8",
+	".mjs": "text/javascript; charset=utf-8",
+	".css": "text/css; charset=utf-8",
+	".json": "application/json; charset=utf-8",
+	".map": "application/json; charset=utf-8",
+	".wgsl": "text/plain; charset=utf-8",
+	".txt": "text/plain; charset=utf-8",
+	".svg": "image/svg+xml",
+	".png": "image/png",
+	".jpg": "image/jpeg",
+	".jpeg": "image/jpeg",
+	".webp": "image/webp",
+	".gif": "image/gif",
+	".ico": "image/x-icon",
+	".wasm": "application/wasm",
+	".woff": "font/woff",
+	".woff2": "font/woff2",
+	".ogg": "audio/ogg",
+	".mp3": "audio/mpeg",
+	".wav": "audio/wav",
+	".webmanifest": "application/manifest+json"
+};
+function mimeType(file) {
+	return MIME[extname(file).toLowerCase()] ?? "application/octet-stream";
+}
+/**
+* The Content-Security-Policy on every `app://` response. Same-origin only: no request can
+* leave the machine from the page, and no inline script runs. Inline styles are allowed
+* because engine widgets set them.
+*/
+var CSP = [
+	"default-src 'self'",
+	"script-src 'self'",
+	"style-src 'self' 'unsafe-inline'",
+	"img-src 'self' data: blob:",
+	"font-src 'self' data:",
+	"media-src 'self' data: blob:",
+	"connect-src 'self'",
+	"worker-src 'self' blob:",
+	"object-src 'none'",
+	"base-uri 'self'",
+	"form-action 'none'",
+	"frame-ancestors 'none'"
+].join("; ");
+/**
+* The dev server URL from `TC_RENDERER_URL`, when it is http(s) on this machine
+* (`localhost`, `127.0.0.1` or `[::1]`), else null.
+*/
+function localDevUrl(url) {
+	if (!url) return null;
+	let u;
+	try {
+		u = new URL(url);
+	} catch {
+		return null;
+	}
+	if (u.protocol !== "http:" && u.protocol !== "https:") return null;
+	if (![
+		"localhost",
+		"127.0.0.1",
+		"[::1]"
+	].includes(u.hostname)) return null;
+	return u;
+}
+/**
+* Whether the renderer may make this request. Only the page's own origin (`app://bundle`, or
+* the local dev server and its HMR socket) and in-memory URLs; everything that would reach
+* the network is cancelled.
+*/
+function requestAllowed(url, dev) {
+	let u;
+	try {
+		u = new URL(url);
+	} catch {
+		return false;
+	}
+	switch (u.protocol) {
+		case `app:`: return u.host === APP_HOST;
+		case "data:":
+		case "blob:":
+		case "devtools:": return true;
+		case "http:":
+		case "https:":
+		case "ws:":
+		case "wss:": return !!dev && u.hostname === dev.hostname && u.port === dev.port;
+		default: return false;
+	}
+}
+/**
+* Whether a top-level navigation to `url` stays on the page's own origin. Compared by scheme
+* and host because `URL.origin` is the string "null" for every custom scheme such as `app:`.
+*/
+function navigationAllowed(url, start) {
+	try {
+		const a = new URL(url);
+		const b = new URL(start);
+		return a.protocol === b.protocol && a.host === b.host && !!a.host;
+	} catch {
+		return false;
+	}
+}
+// packages/host-electron/src/main/switches.ts
+function webgpuSwitches(platform) {
+	const out = [["enable-unsafe-webgpu"]];
+	if (platform === "linux") out.push(["enable-features", "Vulkan"]);
+	return out;
+}
+/**
+* `TC_GPU_SWITCHES` (unpackaged runs only, e.g. CI on SwiftShader): space-separated
+* `--name` or `--name=value`, used instead of the defaults.
+*/
+function parseSwitches(text) {
+	const out = [];
+	for (const raw of text.split(/\s+/)) {
+		const t = raw.replace(/^--/, "");
+		if (!t) continue;
+		const eq = t.indexOf("=");
+		out.push(eq < 0 ? [t] : [t.slice(0, eq), t.slice(eq + 1)]);
+	}
+	return out;
+}
+// packages/host-electron/src/main/main.ts
+/**
+* The ThunderClap desktop shell's main process (D-041, Phase 4). It:
+* - turns WebGPU on explicitly (switches.ts) before the app is ready;
+* - serves the renderer bundle from `app://bundle/` (a fixed, secure origin, so `localStorage`
+*   saves stay put), or the local Vite dev server when `TC_RENDERER_URL` is set (unpackaged);
+* - cancels every request that would leave the machine, denies new windows, navigation away,
+*   webviews and permission prompts;
+* - answers the preload bridge (src/bridge.ts) after checking who called and with what.
+*
+* Unpackaged-only environment (ignored in a packaged build):
+* - `TC_RENDERER_URL`: load this local dev server instead of the bundle (`pnpm desktop:dev`).
+* - `TC_RENDERER_DIR`: serve this directory instead of `out/renderer`.
+* - `TC_USER_DATA`: use this `userData` directory (tests isolate saves with it).
+* - `TC_GPU_SWITCHES`: replace the WebGPU switches (e.g. SwiftShader on a headless runner).
+*/
+var here = dirname(fileURLToPath(import.meta.url));
+var unpackaged = !app.isPackaged;
+var env = (name) => unpackaged ? process.env[name] : void 0;
+var devUrl = localDevUrl(env("TC_RENDERER_URL"));
+var rendererDir = env("TC_RENDERER_DIR") ?? join(here, "renderer");
+var startUrl = devUrl ? devUrl.href : `${APP_ORIGIN}/`;
+var gpuOverride = env("TC_GPU_SWITCHES");
+for (const [name, value] of gpuOverride ? parseSwitches(gpuOverride) : webgpuSwitches(process.platform)) if (value === void 0) app.commandLine.appendSwitch(name);
+else app.commandLine.appendSwitch(name, value);
+var userData = env("TC_USER_DATA");
+if (userData) app.setPath("userData", userData);
+protocol.registerSchemesAsPrivileged([{
+	scheme: "app",
+	privileges: {
+		standard: true,
+		secure: true,
+		supportFetchAPI: true,
+		stream: true
+	}
+}]);
+if (!app.requestSingleInstanceLock()) app.quit();
+else {
+	app.on("second-instance", () => {
+		const w = BrowserWindow.getAllWindows()[0];
+		if (!w) return;
+		if (w.isMinimized()) w.restore();
+		w.focus();
+	});
+	app.whenReady().then(start);
+}
+app.on("window-all-closed", () => app.quit());
+app.on("web-contents-created", (_e, contents) => {
+	contents.on("will-attach-webview", (e) => e.preventDefault());
+	contents.setWindowOpenHandler(({ url }) => {
+		const href = safeExternalHttps(url);
+		if (href && navigationAllowed(contents.getURL(), startUrl)) shell.openExternal(href).catch((err) => {
+			console.error("[thunderclap] openExternal failed:", err);
+		});
+		return { action: "deny" };
+	});
+	contents.on("will-navigate", (e, url) => {
+		if (!navigationAllowed(url, startUrl)) e.preventDefault();
+	});
+	contents.on("will-redirect", (e, url) => {
+		if (!navigationAllowed(url, startUrl)) e.preventDefault();
+	});
+});
+function start() {
+	const ses = session.defaultSession;
+	protocol.handle("app", async (req) => {
+		const file = bundleFile(rendererDir, req.url);
+		if (!file) return new Response("Not found", { status: 404 });
+		try {
+			const body = await readFile(file);
+			return new Response(body, { headers: {
+				"content-type": mimeType(file),
+				"content-security-policy": CSP,
+				"x-content-type-options": "nosniff"
+			} });
+		} catch {
+			return new Response("Not found", { status: 404 });
+		}
+	});
+	ses.webRequest.onBeforeRequest((details, done) => {
+		done({ cancel: !requestAllowed(details.url, devUrl) });
+	});
+	ses.setPermissionRequestHandler((_wc, permission, done) => done(permission === "fullscreen"));
+	ses.setPermissionCheckHandler((_wc, permission) => permission === "fullscreen");
+	installMenu();
+	registerBridge();
+	createWindow();
+}
+function createWindow() {
+	const win = new BrowserWindow({
+		width: 1280,
+		height: 720,
+		minWidth: 640,
+		minHeight: 360,
+		useContentSize: true,
+		show: false,
+		backgroundColor: "#000000",
+		title: app.getName(),
+		autoHideMenuBar: true,
+		webPreferences: {
+			preload: join(here, "preload.cjs"),
+			contextIsolation: true,
+			nodeIntegration: false,
+			sandbox: true,
+			webSecurity: true,
+			spellcheck: false,
+			devTools: unpackaged
+		}
+	});
+	win.once("ready-to-show", () => win.show());
+	const report = (on) => {
+		if (!win.isDestroyed()) win.webContents.send(CH.fullscreenChanged, on);
+	};
+	win.on("enter-full-screen", () => report(true));
+	win.on("leave-full-screen", () => report(false));
+	win.loadURL(startUrl);
+	return win;
+}
+/** macOS needs an app menu for Cmd+Q, copy and paste; elsewhere a game window has none. */
+function installMenu() {
+	if (process.platform !== "darwin") {
+		Menu.setApplicationMenu(null);
+		return;
+	}
+	Menu.setApplicationMenu(Menu.buildFromTemplate([
+		{ role: "appMenu" },
+		{ role: "editMenu" },
+		{
+			role: "windowMenu",
+			submenu: [
+				{ role: "minimize" },
+				{ role: "togglefullscreen" },
+				{ role: "close" }
+			]
+		}
+	]));
+}
+/** The window behind a bridge call, if the call came from our page's main frame. */
+function callerWindow(e) {
+	const win = BrowserWindow.fromWebContents(e.sender);
+	const frame = e.senderFrame;
+	if (!win || !frame || frame !== e.sender.mainFrame) return null;
+	return navigationAllowed(frame.url, startUrl) ? win : null;
+}
+function registerBridge() {
+	ipcMain.handle(CH.openExternal, async (e, url) => {
+		const href = safeExternalHttps(url);
+		if (!callerWindow(e) || !href) return false;
+		try {
+			await shell.openExternal(href);
+			return true;
+		} catch (err) {
+			console.error("[thunderclap] openExternal failed:", err);
+			return false;
+		}
+	});
+	ipcMain.handle(CH.copyText, (e, text) => {
+		if (!callerWindow(e) || typeof text !== "string") return false;
+		clipboard.writeText(text);
+		return true;
+	});
+	ipcMain.handle(CH.fullscreenGet, (e) => callerWindow(e)?.isFullScreen() ?? false);
+	ipcMain.handle(CH.fullscreenSet, async (e, on) => {
+		const win = callerWindow(e);
+		if (!win) return false;
+		const want = on === true;
+		if (win.isFullScreen() === want) return want;
+		const done = new Promise((res) => {
+			const t = setTimeout(res, 2e3);
+			const settle = () => {
+				clearTimeout(t);
+				res();
+			};
+			if (want) win.once("enter-full-screen", settle);
+			else win.once("leave-full-screen", settle);
+		});
+		win.setFullScreen(want);
+		await done;
+		return win.isFullScreen();
+	});
+	ipcMain.on(CH.minimize, (e) => callerWindow(e)?.minimize());
+	ipcMain.on(CH.toggleMaximize, (e) => {
+		const win = callerWindow(e);
+		if (!win) return;
+		if (win.isMaximized()) win.unmaximize();
+		else win.maximize();
+	});
+	ipcMain.on(CH.close, (e) => callerWindow(e)?.close());
+	ipcMain.on(CH.setTitle, (e, title) => {
+		if (typeof title === "string") callerWindow(e)?.setTitle(title.slice(0, 200));
+	});
+}
+export {};

package/out/preload.cjs

@@ -0,0 +1,48 @@
+let electron = require("electron");
+// packages/host-electron/src/bridge.ts
+/** The global the preload defines. */
+var BRIDGE_GLOBAL = "thunderclap";
+/** IPC channels, all prefixed `tc:`. `invoke` channels answer; `send` channels do not. */
+var CH = {
+	openExternal: "tc:open-external",
+	copyText: "tc:copy-text",
+	fullscreenGet: "tc:fullscreen-get",
+	fullscreenSet: "tc:fullscreen-set",
+	/** main → renderer: the new fullscreen state. */
+	fullscreenChanged: "tc:fullscreen-changed",
+	minimize: "tc:window-minimize",
+	toggleMaximize: "tc:window-toggle-maximize",
+	close: "tc:window-close",
+	setTitle: "tc:window-set-title"
+};
+// packages/host-electron/src/preload/preload.ts
+/**
+* The preload: runs sandboxed (`sandbox: true`, `contextIsolation: true`, no Node in the page)
+* and exposes `window.thunderclap` (src/bridge.ts) with `contextBridge`. Each member is a thin
+* IPC call; the main process checks every argument and the caller (src/main/main.ts).
+* Built to a single CommonJS file (out/preload.cjs), as sandboxed preloads require.
+*/
+var bridge = {
+	version: 1,
+	platform: process.platform,
+	openExternal: (url) => electron.ipcRenderer.invoke(CH.openExternal, String(url)),
+	copyText: (text) => electron.ipcRenderer.invoke(CH.copyText, String(text)),
+	fullscreen: {
+		get: () => electron.ipcRenderer.invoke(CH.fullscreenGet),
+		set: (on) => electron.ipcRenderer.invoke(CH.fullscreenSet, on === true),
+		onChange(fn) {
+			const listener = (_e, on) => fn(on === true);
+			electron.ipcRenderer.on(CH.fullscreenChanged, listener);
+			return () => {
+				electron.ipcRenderer.removeListener(CH.fullscreenChanged, listener);
+			};
+		}
+	},
+	window: {
+		minimize: () => electron.ipcRenderer.send(CH.minimize),
+		toggleMaximize: () => electron.ipcRenderer.send(CH.toggleMaximize),
+		close: () => electron.ipcRenderer.send(CH.close),
+		setTitle: (title) => electron.ipcRenderer.send(CH.setTitle, String(title))
+	}
+};
+electron.contextBridge.exposeInMainWorld(BRIDGE_GLOBAL, bridge);

package/package.json

@@ -1,6 +1,78 @@
 {
   "name": "@thunderclap-engine/host-electron",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "productName": "ThunderClap",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "ThunderClap's Electron host: a desktop shell (main process and preload bridge) and createElectronHost() for the renderer. It knows nothing about any game. Games depend on @thunderclap-engine/engine themselves; everything the shell runs is bundled into out/, so it has no runtime dependencies.",
+  "license": "MIT",
+  "author": "ThunderClap",
+  "homepage": "https://github.com/Mandalorian007/thunderclap-engine/tree/main/packages/host-electron#readme",
+  "bugs": {
+    "url": "https://github.com/Mandalorian007/thunderclap-engine/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Mandalorian007/thunderclap-engine.git",
+    "directory": "packages/host-electron"
+  },
+  "keywords": [
+    "thunderclap",
+    "electron",
+    "desktop",
+    "webgpu",
+    "game-engine"
+  ],
+  "sideEffects": false,
+  "main": "out/main.mjs",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "out/main.mjs",
+    "out/preload.cjs",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "peerDependencies": {
+    "@thunderclap-engine/engine": "^1.0.0",
+    "electron": ">=45.0.0"
+  },
+  "peerDependenciesMeta": {
+    "electron": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.6.4",
+    "@playwright/test": "^1.64.1",
+    "@types/node": "^26.6.6",
+    "@webgpu/types": "^0.1.74",
+    "electron": "^45.2.2",
+    "electron-builder": "^26.18.0",
+    "happy-dom": "^21.0.4",
+    "typescript": "^7.0.2",
+    "vite": "^8.3.5",
+    "vitest": "^5.0.5",
+    "@thunderclap-engine/engine": "1.1.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.node.json",
+    "lint": "biome check .",
+    "test": "vitest run",
+    "check": "pnpm typecheck && pnpm lint && pnpm test",
+    "build": "node scripts/build.mjs",
+    "dev": "node scripts/dev.mjs",
+    "dist": "node scripts/dist.mjs",
+    "test:e2e": "node scripts/build.mjs && playwright test"
+  },
+  "types": "./dist/index.d.ts"
 }