@homie-rocks/studio 0.31.0 → 0.32.0

package/standalone/STANDALONE.md

@@ -0,0 +1,313 @@
+# Standalone copies of a game
+
+`homie-studio standalone` turns a game of your studio into an app of its own:
+
+| Target | Made with | What comes out | Where it can go |
+| --- | --- | --- | --- |
+| `mac` | Electron | `out/mac/<debug or release>/<Name>.app` | Steam |
+| `windows` | Electron | `out/windows/<debug or release>/<id>.exe` and its files | Steam |
+| `linux` | Electron | `out/linux/<debug or release>/<id>` and its files | Steam |
+| `ios` | Capacitor, Xcode | a simulator `.app`, or an `.ipa` with `--release` | the App Store |
+| `android` | Capacitor, Gradle | a debug `.apk`, or an `.aab` with `--release` | Google Play |
+
+Each is **the kind of file that store accepts for upload**. Whether a store takes your game is the store's
+decision: its review, its fees and its rules are its own, and nothing here makes an app pass (see "Before you
+spend money", below).
+
+It is the **same web build** of the game, the one `homie-studio build` makes and your site serves, in the
+thinnest shell each platform has. Nothing about one game lives in a shell. Multiplayer still goes through your
+studio's own deployed site: the app asks its Lobby for a room and opens the room's socket, exactly as the play
+page does. With no connection, or when no room answers, the game plays offline with its bots.
+
+```sh
+npx --no-install homie-studio standalone plan <game>      # what would be built, what is missing; changes nothing
+npx --no-install homie-studio standalone build <game>     # every target this computer can make
+npx --no-install homie-studio standalone build <game> --for mac,windows
+npx --no-install homie-studio standalone run <game>       # the built desktop copy, here (--for ios | android)
+npx --no-install homie-studio standalone steam <game>     # Steam's build file; uploads nothing
+npx --no-install homie-studio standalone ci <game>        # a GitHub workflow that builds all five
+```
+
+In chat it is one tool, `game_standalone` (with `plan: true` first).
+
+## What the standalone game does not have (v1)
+
+Say this to whoever will ship it, before they do.
+
+- **Player accounts and sign-in.** The app has no sign-in and no name entry. A player is a guest with a two-word
+  handle; an account made on the site is not known to the app.
+- **Cloud saves.** Saves and settings are kept on the device only (the saves helper's local mode). They do not
+  follow a player to the site or to another device, and they are **lost when the app is uninstalled**.
+- **The shop.** Nothing is sold in the app. The app stores have their own rules for selling, and none of that is
+  built.
+- **Room chat.** Off in the app: it has no report or mute controls yet, and a chat without them is not shipped.
+- **Watching, the big screen, the owner's controls.** The app only plays.
+- **Servers and private doors.** The app plays on the public server through an open door. A game that is private
+  or invite-only, or a server behind an account or an invite, plays offline in the app.
+- **Automatic updates.** The app is the build it was made from. A newer version reaches players only when you
+  build again and ship the update through Steam or the store.
+- **Steam's overlay, achievements and friends.** None of it has been run. The desktop app passes the switch the
+  overlay needs when Steam starts it, but Electron apps often do not show Steam's overlay, and achievements,
+  rich presence and friend invites are not wired.
+- **Uploading, and a store's yes.** Builds are made on your computer and the upload steps are printed. Nothing is
+  sent to Steam, App Store Connect or Google Play for you, and nothing here makes an app pass a review.
+- **A signed Windows build.** Unsigned in v1: opened outside Steam, Windows shows its unknown-publisher warning.
+
+## What has been run and what has not
+
+This is version 1, and it says what it knows. As of 2026-10-06, by the people who wrote it, on one Mac:
+
+**Run and seen:**
+
+- The macOS build (Apple silicon, and the universal one a release makes) started and the game loaded with its
+  bots, from its own `app://game` origin, with no file failing to load. Every desktop build for the computer it
+  is made on is started once like this, and its result says "started here and loaded the game: yes" or "NO".
+- That build, pointed at a studio's local dev server, got a room from the Lobby and opened the room's socket.
+- A macOS build signed ad hoc with the hardened runtime and the Steam entitlements started and loaded the game.
+- The iOS simulator build ran in the iOS Simulator; the Android debug build ran in the Android emulator. Both
+  offline, with their bots.
+- An Android release bundle was signed by Gradle with a test key (the key's passwords given through the
+  environment), and the bundle carries that key's certificate.
+- The Windows build's program carries the game's icon and its name; the Linux build is a Linux program. Both
+  were made on the Mac.
+
+**Never run:**
+
+- **The Windows and Linux builds have never been started**, on any computer. On Ubuntu 24.04 and later a program
+  in a plain folder like `out/linux/` may refuse to start outside Steam until its `chrome-sandbox` file is owned
+  by root with mode 4755, or it is started with `--no-sandbox`; an installer normally does the first, and there
+  is none.
+- **Nothing has been started by Steam.** Not the overlay, not the Linux build inside Steam's runtime, not the
+  Steam API binding. `steam/app_build.vdf` is written from Steam's documented format and has never been run
+  through `steamcmd`.
+- **A macOS app signed with a Developer ID, and notarization.** The code asks the signer and the notary and then
+  checks the result (`codesign --verify`, `xcrun stapler validate`); it says "notarized" only when the second
+  agrees. That path has not been run with a real identity. Opening a notarized app on another Mac was not tried.
+- **The iOS archive and its `.ipa`.** It needs Xcode signed in to an Apple account of your team; it was not run.
+- **Anything on a real phone**, and a phone build that plays online.
+- **The GitHub workflow.** It is checked as text. Read the first run's log.
+- **A copy meeting a deployed site**, and an old copy meeting a newer site, outside the tests.
+- **Building from Windows or Linux.**
+
+When one of these fails for you, that is news to us: tell Homie.
+
+## Before a copy can find rooms
+
+Your studio must be on `@homie-rocks/studio` 0.32.0 or later **and deployed**. The app's page is not served by
+your site, so it is another origin to your Worker; 0.32.0 is the first Worker that lets an app read the Lobby's
+answer. A copy pointed at an older site plays offline.
+
+The site's address is **built into every copy** (`--site <address>`, else `HOMIE_STANDALONE_SITE`, else the
+address your last deploy from this computer got). A copy that has shipped keeps it for good, so put the studio
+on its own domain (`studio.json` `cloudflare.domain`) before you ship: a workers.dev address belongs to the
+Cloudflare account and changes if the Worker is renamed.
+
+A game that loads something from another site at run time (a web font, a picture, an API) still needs a
+connection for that in the app, exactly as on the web: bundle what the game must have offline. And a game whose
+`index.html` carries a Content-Security-Policy that forbids inline scripts never hears the shell (a copy adds
+one inline script to that page) and plays offline only; the plan warns when it sees one.
+
+## Versions: an old copy and a new site
+
+Name the game's revision in `game.json` (`"netplay": { "version": "1" }`, NETPLAY.md section 23) before you
+ship, and raise it with every change an older copy cannot play with. Then:
+
+- a copy asks the Lobby for a room of **its own** revision, so copies of one revision keep playing with each
+  other, whatever the site runs now. The Lobby keeps rooms for the live revision and at most eight others at a
+  time; a copy on a ninth is told to play offline for now;
+- a copy that knocks at a room on a newer revision (a friend's invite link) is refused, plays on by itself, and
+  says so: "Update <Name> to play online with everyone." It never reloads: only an update of the app brings a
+  newer build. From then on it shows that line in place of Invite, because its invite would send a friend's
+  browser to the newer version, which the copy cannot join;
+- `homie-studio deploy` (and `deploy --plan`) says when a deploy makes a different revision live than the copies
+  you built, and what that means for them.
+
+## game.json
+
+Everything is optional until a release:
+
+```json
+"standalone": {
+  "appId": "com.example.gemrush",
+  "version": "1.0.0",
+  "build": 1,
+  "orientation": "landscape",
+  "icon": "icon.png",
+  "steam": { "app": 0, "depots": { "windows": 0, "mac": 0, "linux": 0 } }
+}
+```
+
+- `appId`: the app's id in both stores (letters and digits in dotted parts, each starting with a letter). With
+  none, a build to try uses a made-up one: your domain reversed, else `rocks.homie.<studio>`, then the game's id.
+  **`--release` refuses until you write one**: a store never lets it change.
+- `version`, `build`: what a player sees and the store's build number (`--build <n>` overrides the number).
+- `orientation`: `landscape`, `portrait` or `any` (phones).
+- `icon`: a picture in the game's folder. Without it: `games/<id>/icon.png`, else the cover cropped square, else
+  a tile with the game's first letter. Stores want a real square 1024 by 1024 picture.
+- `steam`: your App ID and one Depot ID for each operating system, for `standalone steam`.
+
+The app's name is the game's name; its publisher is the studio's. A name with a character a file's name cannot
+have (`: / \ " < > | ? *`) is still the app's name on phones and in the window's title; the desktop app's file,
+and what macOS shows in its menu bar and Dock, has a `-` in its place. Every path the command reports is where
+the file is.
+
+## Where everything is
+
+All of it is in `.studio/standalone/<id>/`, which is git-ignored. Never edit it; never commit it.
+
+```
+web/         the shell's page (index.html, shell.js, shell.css), config.js, and game/ (the built game)
+electron/    main.cjs, files.cjs and app.json, with a copy of web/
+ios/  android/   the native projects Capacitor makes
+icons/  assets/  the icon in every size
+steam/       app_build.vdf
+out/<target>/debug/    out/<target>/release/     what was built; a debug build never replaces a release
+built.json   for each target, what its debug and its release copy were built from
+node_modules/  package-lock.json   the wrapper tools
+```
+
+**Made again by every build:** `web/`, `electron/`, the icons, the config files, and the `out/` folder of what
+is being built. **Kept between builds:** `node_modules/` (installed on the first build, a few hundred MB, and
+again only when a pin changed or an install did not finish), `ios/` and `android/` (made by Capacitor once, and
+again when the app's id or its name changed; their versions, orientation and icons are set on every build), and
+the other kind's `out/` folder.
+
+The wrapper tools are pinned twice: each tool at one exact version (`lib/standalone-pins.json`), and the whole
+tree under them at exact versions with checksums (`lib/standalone-lock.json`, copied in as the project's
+lockfile). A studio that never makes a standalone copy downloads none of them. When a file of theirs is
+missing, the build installs them again, once, and says so.
+
+`web/game/` is your site's build byte for byte, but for one script added to its `index.html`, which hands the
+netplay helper the shell's word as your Worker does on the site.
+
+## What each target needs
+
+`standalone plan` checks this computer and says, for each target, whether it can be built here. A target whose
+tool is missing is **skipped** with its fix; the others still build. Nothing is installed for you. A row says
+"ok" only for what was looked at: a name in the environment is said as "set, checked later", not as working.
+
+- **mac**: a Mac.
+- **windows**, **linux**: any computer (a Windows build from a Mac needs no Wine).
+- **ios**: a Mac with Xcode and its iOS platform.
+- **android**: the Android SDK with the Android 36 platform (Android Studio installs both) and JDK 21 (22 to 24
+  also work; Android Studio's own JDK is used when the one on your PATH does not fit, for every step).
+
+A computer that cannot make a target can still get it: `standalone ci <game>` writes
+`.github/workflows/standalone.yml`, which builds each target on GitHub's own Windows, Linux and macOS machines
+when you start it by hand. Set the repository variable `HOMIE_SITE` to your studio's address first. Its macOS
+and iOS jobs never make a release (it has no Apple certificate): the macOS app it makes is unsigned and the iOS
+one is a simulator build.
+
+## What a build's result means
+
+- **built**: the tool finished and the file is at the path given. The desktop build for this computer's own
+  system was also started once: "started here and loaded the game: yes" or "NO". Every other target says
+  "built, not started on this computer". Built is not the same as works.
+- **skipped**: a tool is missing; the fix is printed.
+- **failed**: in the tool's own words.
+- **UNSIGNED**: a release that was built and could not be signed (or signed and not notarized). No store takes
+  it, and the command does not report success.
+
+The command succeeds only when something was built, nothing failed, no release came out unsigned, and every
+target you named with `--for` was built.
+
+## A release, and signing
+
+`--release` makes the file a store or Steam accepts for upload. Signing reads **environment variables only**:
+never a file in the studio, never the chat. Only the one tool that signs is given them; npm, Capacitor and
+every script they run are not.
+
+| Variable | For |
+| --- | --- |
+| `HOMIE_APPLE_IDENTITY` | macOS: the name of your "Developer ID Application" identity. The app is signed with the hardened runtime |
+| `HOMIE_APPLE_NOTARY_PROFILE` | macOS: a notarytool keychain profile. Make it yourself, in your own terminal: `xcrun notarytool store-credentials "homie-notary"` |
+| `HOMIE_APPLE_TEAM` | iOS: your team id. Xcode, signed in to an Apple account of that team, signs the archive and exports an `.ipa` |
+| `HOMIE_ANDROID_KEYSTORE`, `HOMIE_ANDROID_KEYSTORE_PASSWORD`, `HOMIE_ANDROID_KEY_ALIAS`, `HOMIE_ANDROID_KEY_PASSWORD` | Android: your upload key. The passwords reach Gradle through its environment, never a command line |
+
+Set them where your AI's commands run, never in the chat: in a terminal, `export NAME=…` and start your AI from
+that terminal; for a desktop app on a Mac, `launchctl setenv NAME …` in Terminal and then open the app again; in
+the GitHub workflow they are repository secrets.
+
+A macOS release without the identity is built and marked UNSIGNED. Signed without the profile it is marked NOT
+NOTARIZED. With both, it is called notarized only when `xcrun stapler validate` confirms the ticket on the
+finished app. An Android release without all four values is built and marked UNSIGNED. A macOS game with a
+Steam app is signed with entitlements that let the Steam client load its overlay library; any other is signed
+with the signer's own defaults.
+
+## Before you spend money
+
+What a store asks of you changes; these were true when this was written (2026-10-06), so check each store's own
+page before you pay.
+
+- **Apple**: the Apple Developer Program is a yearly membership (US$99 a year), needed to sign for iOS and to
+  notarize for macOS. Apple reviews every app, and its guidelines let it reject one it judges to be a web site
+  in a wrapper. A game whose files are all in the app and that plays offline is a better case than a page that
+  loads from the web, and nothing guarantees approval.
+- **Google Play**: a one-time registration fee (US$25). A personal account created since late 2023 must run a
+  closed test with a number of testers for two weeks before it may publish to everyone.
+- **Steam**: Steam Direct's fee is paid for each app (US$100, returned after the app earns a set amount), and
+  Steam makes a new partner and a new app wait (about thirty days after paying, and a store page live for about
+  two weeks) before release. Steam asks macOS builds to be signed and notarized.
+
+## Steam
+
+`standalone steam <game>` writes `steam/app_build.vdf` from your numbers, with each depot inside it pointing at
+that system's release build (`out/<os>/release/`), and prints the one `steamcmd` command to run yourself. With
+no numbers yet it says what to create in Steamworks, and the launch options to set there: `<id>.exe`,
+`<Name>.app`, `<id>`. **For the Linux one, put `--no-sandbox` in its arguments**: inside Steam's Linux runtime
+the browser engine's own sandbox cannot start, and the app does not turn it off by itself.
+
+When Steam starts the game (Steam sets `SteamAppId` for what it starts), the app passes the one switch Steam's
+overlay needs to draw (`in-process-gpu`). That is all it does for the overlay, it has not been run under Steam,
+and many Electron apps show no overlay at all. `standalone run` puts `steam_appid.txt` beside the app it starts
+for development, never in `out/`.
+
+Steam's own API is off unless you ask: `"steam": { "api": true }` and `HOMIE_STEAMWORKS_SDK=<the SDK folder you
+downloaded from Steamworks>`. The binding (`steamworks-ffi-node`) is then installed into the desktop app and
+Steam's libraries are copied from your SDK. It has never been run. The app's log says whether it started
+("the Steamworks binding started", or that it did not and why), and the game runs either way. No achievements
+are wired in v1.
+
+## The shells, briefly
+
+- **Desktop** (`standalone/electron/main.cjs`): one window on `app://game/`, served from the app's own `web/`
+  folder and nothing else (`files.cjs` decides which file an address names; a test runs it with hostile
+  addresses). No Node in the page, no preload, sandboxed; a link opens in the person's browser; the page may
+  only lock the pointer, go full screen and copy an invite link. Its storage and its single-instance lock are
+  kept under the app's id, so two games never share them. A shipped copy has no developer tools and, on macOS, a
+  menu of its own (the app, Edit, Window). F11 or Alt+Enter toggles full screen. `--smoke` is its self-check: it
+  loads, waits, and prints one line of JSON.
+- **Phones**: Capacitor's stock shell with the web folder bundled (`capacitor://localhost` on iOS,
+  `https://localhost` on Android). Never `server.url`: the app does not load its page from a site.
+- **The page** (`standalone/shell/`): the room button and its sheet, as on the play page. Invite shares the
+  room's address on your site, so a friend in a browser joins the same room; Join a room takes a code; New
+  private room makes one; Quick play asks the Lobby. When the Lobby has not answered in a second and a half the
+  game starts offline, and a room that arrives later is offered, never switched to. A seat is remembered across
+  restarts of the app.
+
+## What the game's own code can reach
+
+On the web, your Worker serves a game into a sandboxed frame that cannot touch the page around it. In an app the
+game's frame is the shell's own origin (that is what lets its saves work), so **the game's code is trusted with
+everything the app's page has**:
+
+- its own storage (saves, settings, the room key), and the shell's page around it;
+- on phones, **Capacitor's native bridge**. The shell uses no plugin, but the bridge is in every frame of the
+  app, and through it code can ask the native side for things a web page cannot: requests that skip the
+  browser's cross-origin rules, the native cookie store, and whatever plugins a future version adds.
+
+This is your own game's code, so it is yours to trust. It matters when a game runs **somebody else's** code: an
+ad or analytics script, a script loaded from another site, a part you did not read. In the app that code has
+the same reach. Do not load scripts from the network in a game you ship as an app.
+
+## What the Worker allows an app
+
+One thing: `POST /<game>/api/lobby` from `app://game`, `capacitor://localhost` or `https://localhost` gets an
+answer the app's page may read, whatever the answer is (`worker/standalone.mjs`). No credentials cross, the
+Lobby is never opened to every origin, an app may only ask for the public server, and every POST that must come
+from your own site's pages (players, saves, the shop, chat reports, the office) still refuses an app. That is
+why an app has no account, no cloud saves and no shop.
+
+An app says which revision it is, and anybody can claim to be an app. So the Lobby keeps rooms for at most
+eight revisions besides the live one, never gives a server more rooms than it may have whatever revision asks,
+and keeps at most 512 rooms for a game in all (rooms nobody is seated in make way first).

package/standalone/electron/files.cjs

@@ -0,0 +1,50 @@
+/*
+ * Which file a request to the desktop shell names, and which bytes of it (standalone/STANDALONE.md). Nothing here
+ * needs Electron, so a test runs it with hostile addresses: main.cjs serves exactly what these two say.
+ */
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+
+/** The file an `app://game/…` address names inside `web`, or null: another host, a path that climbs out, or nothing there. */
+function fileFor(web, address) {
+  let url;
+  try { url = new URL(address); } catch { return null; }
+  if (url.protocol !== 'app:' || url.host !== 'game') return null;
+  let rel;
+  try { rel = decodeURIComponent(url.pathname); } catch { return null; }
+  if (rel.includes('\0') || rel.includes('\\')) return null;
+  const abs = path.resolve(web, `.${path.posix.normalize(`/${rel}`)}`);
+  if (abs !== web && !abs.startsWith(web + path.sep)) return null;
+  for (const f of [abs, path.join(abs, 'index.html')]) {
+    try {
+      // A link inside web/ that points out of it is not a file of the game.
+      const real = fs.realpathSync(f);
+      if (fs.statSync(real).isFile() && (real === fs.realpathSync(web) || real.startsWith(fs.realpathSync(web) + path.sep))) return f;
+    } catch { /* next */ }
+  }
+  return null;
+}
+
+/**
+ * The part of a file of `size` bytes a Range header asks for: { start, end } (both inside the file), 'whole' when
+ * there is no usable header (the whole file is the answer), or 'none' when the range lies outside the file (416).
+ */
+function rangeOf(header, size) {
+  const m = /^bytes=(\d{0,15})-(\d{0,15})$/.exec(String(header || '').trim());
+  if (!m || (m[1] === '' && m[2] === '')) return 'whole';
+  if (!(size > 0)) return 'none';
+  if (m[1] === '') { const n = Number(m[2]); return n > 0 ? { start: Math.max(0, size - n), end: size - 1 } : 'none'; }
+  const start = Number(m[1]);
+  const end = m[2] === '' ? size - 1 : Math.min(Number(m[2]), size - 1);
+  return start > end || start >= size ? 'none' : { start, end };
+}
+
+/** Where a frame of the page may go: the app's own files; and for a frame inside the game, a blob or a srcdoc of its own. */
+function mayNavigate(address, { main = true } = {}) {
+  const url = String(address);
+  if (url.startsWith('app://game/')) return true;
+  return !main && (url === 'about:srcdoc' || url === 'about:blank' || url.startsWith('blob:app://game/'));
+}
+
+module.exports = { fileFor, rangeOf, mayNavigate };

package/standalone/electron/main.cjs

@@ -0,0 +1,139 @@
+/*
+ * THE DESKTOP SHELL (standalone/STANDALONE.md): one window that shows the game's web folder, and nothing else. It is
+ * the same file for every game: what differs is app.json beside it. The page gets no Node, no preload and no way out
+ * of its own folder; a link opens in the person's browser.
+ *
+ *   --smoke[=<ms>]   a self-check for `homie-studio standalone`: load, wait, print ONE line of JSON saying where the
+ *                    page is, whether the game's frame loaded, what failed to load and what the console said, exit.
+ *                    With --shot=<file.png>, a picture of the window as it was then.
+ */
+'use strict';
+const { app, BrowserWindow, Menu, net, protocol, session, shell } = require('electron');
+const fs = require('node:fs');
+const path = require('node:path');
+const { Readable } = require('node:stream');
+const { pathToFileURL } = require('node:url');
+const { fileFor, rangeOf, mayNavigate } = require('./files.cjs');
+
+const cfg = JSON.parse(fs.readFileSync(path.join(__dirname, 'app.json'), 'utf8'));
+const WEB = path.join(__dirname, 'web');
+const ORIGIN = 'app://game';
+const smokeArg = process.argv.find((a) => /^--smoke(=\d+)?$/.test(a));
+const SMOKE = smokeArg ? Number(smokeArg.split('=')[1]) || 6000 : 0;
+
+// Nothing a page does may raise Electron's own error dialog over the game: said in the log, and the game goes on.
+process.on('uncaughtException', (error) => { try { console.error(`shell: ${String(error && error.stack ? error.stack : error).slice(0, 600)}`); } catch { /* no console */ } });
+
+// This game's own storage and its own single-instance lock: two games with the same name never share either.
+// The self-check keeps nothing: its storage is a folder of its own in the temporary folder, removed when it ends.
+const smokeData = SMOKE ? fs.mkdtempSync(path.join(require('node:os').tmpdir(), 'standalone-smoke-')) : null;
+if (smokeData) { app.setPath('userData', smokeData); app.on('quit', () => { try { fs.rmSync(smokeData, { recursive: true, force: true }); } catch { /* the system clears it */ } }); }
+else if (/^[A-Za-z][A-Za-z0-9.]{2,120}$/.test(cfg.appId || '')) app.setPath('userData', path.join(app.getPath('appData'), cfg.appId));
+
+// The page's own origin: a standard, secure one, so its storage, its modules and its fetches behave as on a site.
+protocol.registerSchemesAsPrivileged([{ scheme: 'app', privileges: { standard: true, secure: true, supportFetchAPI: true, stream: true } }]);
+
+/*
+ * STARTED BY STEAM (Steam sets SteamAppId for what it starts; a game.json with a Steam app is not enough). The
+ * overlay is a library the Steam client loads into this process, and it draws only when the GPU runs in the browser
+ * process, so that switch is passed. This has never been run under Steam, and Electron apps often show no overlay.
+ * Chromium's sandbox is NOT turned off here: a switch added at this point is too late for it, and inside Steam's
+ * Linux container the way to do that is the launch option --no-sandbox, set in Steamworks (STANDALONE.md says so).
+ */
+const underSteam = Boolean(process.env.SteamAppId || process.env.SteamGameId || process.env.SteamOverlayGameId);
+if (underSteam) app.commandLine.appendSwitch('in-process-gpu');
+// Steam's own API, only when game.json asked for it and Steam started the game: whatever happens is said in the log,
+// and the game runs either way. This binding has never been run by the people who wrote this file.
+if (underSteam && cfg.steam && cfg.steam.api) {
+  try {
+    const steam = require('steamworks-ffi-node');
+    const s = (steam.SteamworksSDK || steam.default || steam).getInstance();
+    // Steam's own libraries, copied beside this file from the SDK the studio's owner downloaded (never shipped by Homie).
+    s.setSdkPath(path.join(__dirname, 'steamworks_sdk'));
+    const started = s.init({ appId: cfg.steam.app });
+    if (started) { console.log('steam: the Steamworks binding started'); app.on('before-quit', () => { try { s.shutdown(); } catch { /* gone */ } }); }
+    else console.error('steam: the Steamworks binding said it did not start (init answered false); playing without it');
+  } catch (error) { console.error(`steam: the Steamworks binding did not start (${String(error && error.message).slice(0, 200)}); playing without it`); }
+}
+
+const MEDIA = { '.mp3': 'audio/mpeg', '.ogg': 'audio/ogg', '.wav': 'audio/wav', '.m4a': 'audio/mp4', '.mp4': 'video/mp4', '.webm': 'video/webm' };
+async function serve(request) {
+  const file = fileFor(WEB, request.url);
+  if (!file) return new Response('not found', { status: 404, headers: { 'content-type': 'text/plain' } });
+  // A part of a file (a player seeking in a song): answered here, since a file fetch is always the whole of it.
+  let size = 0;
+  try { size = fs.statSync(file).size; } catch { return new Response('not found', { status: 404 }); }
+  const range = rangeOf(request.headers.get('range'), size);
+  if (range === 'whole') return net.fetch(pathToFileURL(file).toString());
+  if (range === 'none') return new Response(null, { status: 416, headers: { 'content-range': `bytes */${size}` } });
+  const stream = fs.createReadStream(file, range);
+  // A player that stops asking (a seek, a closed page) ends the stream early: that is not an error of anybody's.
+  stream.on('error', () => {});
+  return new Response(Readable.toWeb(stream), { status: 206, headers: { 'content-type': MEDIA[path.extname(file).toLowerCase()] || 'application/octet-stream', 'content-length': String(range.end - range.start + 1), 'content-range': `bytes ${range.start}-${range.end}/${size}`, 'accept-ranges': 'bytes' } });
+}
+
+/** macOS wants a menu bar: the app's own (Quit), Edit (so copy and paste work in the room-code field) and Window. No Reload, no tools, no Help. */
+function menu() {
+  if (process.platform !== 'darwin') return null;
+  return Menu.buildFromTemplate([
+    { label: cfg.name, submenu: [{ role: 'about', label: `About ${cfg.name}` }, { type: 'separator' }, { role: 'hide', label: `Hide ${cfg.name}` }, { role: 'hideOthers' }, { role: 'unhide' }, { type: 'separator' }, { role: 'quit', label: `Quit ${cfg.name}` }] },
+    { label: 'Edit', submenu: [{ role: 'undo' }, { role: 'redo' }, { type: 'separator' }, { role: 'cut' }, { role: 'copy' }, { role: 'paste' }, { role: 'selectAll' }] },
+    { label: 'Window', submenu: [{ role: 'minimize' }, { role: 'zoom' }, { role: 'togglefullscreen' }] },
+  ]);
+}
+
+function open() {
+  const win = new BrowserWindow({
+    width: cfg.width || 1280, height: cfg.height || 720, minWidth: 480, minHeight: 320, show: !SMOKE,
+    title: cfg.name, backgroundColor: cfg.background || '#04060c', autoHideMenuBar: true,
+    ...(process.platform === 'linux' && fs.existsSync(path.join(__dirname, 'icon.png')) ? { icon: path.join(__dirname, 'icon.png') } : {}),
+    // The developer tools are for the copy a studio runs from its own folder, never for the one it ships.
+    webPreferences: { contextIsolation: true, nodeIntegration: false, sandbox: true, backgroundThrottling: false, devTools: !app.isPackaged },
+  });
+  const wc = win.webContents;
+  wc.on('will-navigate', (event, url) => { if (!mayNavigate(url, { main: true })) event.preventDefault(); });
+  wc.on('will-frame-navigate', (event) => { if (!mayNavigate(event.url, { main: event.isMainFrame })) event.preventDefault(); });
+  wc.setWindowOpenHandler(({ url }) => { if (/^https:\/\//i.test(url)) shell.openExternal(url); return { action: 'deny' }; });
+  wc.on('before-input-event', (event, input) => {
+    if (input.type === 'keyDown' && (input.key === 'F11' || (input.key === 'Enter' && input.alt))) { win.setFullScreen(!win.isFullScreen()); event.preventDefault(); }
+  });
+  if (SMOKE) smoke(win);
+  win.loadURL(`${ORIGIN}/index.html`);
+}
+
+/** The self-check: what a person would see go wrong, as one line of JSON, then exit (1 when the game did not load). */
+function smoke(win) {
+  const wc = win.webContents;
+  const failed = []; const errors = []; let requests = 0;
+  session.defaultSession.webRequest.onCompleted((d) => { requests += 1; if (d.statusCode >= 400) failed.push(`${d.statusCode} ${d.url}`.slice(0, 200)); });
+  session.defaultSession.webRequest.onErrorOccurred((d) => { failed.push(`${d.error} ${d.url}`.slice(0, 200)); });
+  wc.on('console-message', (event) => { if (event.level === 'error') errors.push(String(event.message).slice(0, 300)); });
+  wc.on('did-fail-load', (event, code, why, url) => failed.push(`${code} ${why} ${url}`.slice(0, 200)));
+  const probe = `(() => { const f = document.querySelector('iframe.game'); let g = null;
+    try { const w = f.contentWindow, d = f.contentDocument, n = w.__homieNet; g = { href: w.location.href, ready: d.readyState, canvas: d.querySelectorAll('canvas').length, net: w.HOMIE_NET ? { url: w.HOMIE_NET.url, room: w.HOMIE_NET.room || null, app: w.HOMIE_NET.app === true } : null, helper: n ? { role: n.role, offline: n.offline, connected: n.connected, link: n.link, roster: Array.isArray(n.roster) ? n.roster.length : null } : null }; } catch (e) { g = { error: String(e) }; }
+    return { origin: location.origin, title: document.title, shell: window.__shell ? { room: window.__shell.room, online: window.__shell.online, link: window.__shell.link, starts: window.__shell.starts } : null, game: g }; })()`;
+  setTimeout(async () => {
+    let page = null;
+    try { page = await wc.executeJavaScript(probe); } catch (error) { errors.push(`probe: ${String(error && error.message)}`); }
+    const shot = process.argv.find((x) => x.startsWith('--shot='));
+    if (shot) { try { fs.writeFileSync(shot.slice(7), (await wc.capturePage()).toPNG()); } catch (error) { errors.push(`shot: ${String(error && error.message)}`); } }
+    const loaded = Boolean(page && page.game && page.game.ready === 'complete');
+    process.stdout.write(`${JSON.stringify({ smoke: 1, ok: loaded && !failed.length && !errors.length, loaded, packaged: app.isPackaged, requests, failed, errors, ...page })}\n`);
+    app.exit(loaded ? 0 : 1);
+  }, SMOKE);
+}
+
+if (!SMOKE && !app.requestSingleInstanceLock()) app.quit();
+else {
+  app.on('second-instance', () => { const w = BrowserWindow.getAllWindows()[0]; if (w) { if (w.isMinimized()) w.restore(); w.focus(); } });
+  app.whenReady().then(() => {
+    protocol.handle('app', serve);
+    // The page may lock the pointer, go full screen and put an invite link on the clipboard. Nothing else is asked for.
+    const allowed = new Set(['pointerLock', 'fullscreen', 'clipboard-sanitized-write']);
+    session.defaultSession.setPermissionRequestHandler((wc, permission, done) => done(allowed.has(permission)));
+    session.defaultSession.setPermissionCheckHandler((wc, permission) => allowed.has(permission));
+    Menu.setApplicationMenu(menu());
+    open();
+  });
+  app.on('window-all-closed', () => app.quit());
+}

package/standalone/electron/pack.mjs

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+/**
+ * Package the desktop app with @electron/packager (standalone/STANDALONE.md):
+ * `node pack.mjs <platform> <arch> <debug|release>`, run in the standalone project by `homie-studio standalone
+ * build`. It is the same file for every game: what it packs is electron/ (main.cjs, app.json, the web folder),
+ * unpacked beside the Electron binary (no asar: Steam patches a build file by file, and the game's files stay the
+ * files the web build made). The result is out/<os>/<debug|release>/: that folder IS the app's folder.
+ *
+ * macOS signing comes from the environment only, never from a file or an argument:
+ *   HOMIE_APPLE_IDENTITY         the signing identity's name ("Developer ID Application: …", or - for an ad hoc
+ *                                signature that only this Mac trusts); with it the app is signed with the hardened
+ *                                runtime. The signer's own entitlements are used, which differ for the app and each
+ *                                helper; a game with a Steam app gets entitlements.mac.plist instead (see the
+ *                                generator), because the signer replaces, never merges. So does an ad hoc
+ *                                signature: with no team in it, the hardened runtime would refuse the app's own
+ *                                frameworks unless library validation is off
+ *   HOMIE_APPLE_NOTARY_PROFILE   a notarytool keychain profile (xcrun notarytool store-credentials, made by the
+ *                                person in their own terminal); with it the signed app is sent to Apple's notary
+ * "notarized" is said only when `xcrun stapler validate` agrees afterwards; otherwise the result says what was asked
+ * for and that it was not confirmed.
+ * It prints ONE line of JSON: { ok, platform, arch, path, app, exe, signed, notarized, checks } or { ok: false, why }.
+ */
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { packager } from '@electron/packager';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const [platform, arch, kind = 'debug'] = process.argv.slice(2);
+const FOLDER = { darwin: 'mac', win32: 'windows', linux: 'linux' };
+const say = (o) => process.stdout.write(`${JSON.stringify(o)}\n`);
+
+try {
+  if (!FOLDER[platform] || !arch || !['debug', 'release'].includes(kind)) throw new Error('usage: node pack.mjs darwin|win32|linux <arch> debug|release');
+  const meta = JSON.parse(readFileSync(join(here, 'electron', 'package.json'), 'utf8'));
+  const app = JSON.parse(readFileSync(join(here, 'electron', 'app.json'), 'utf8'));
+  const electron = JSON.parse(readFileSync(join(here, 'node_modules', 'electron', 'package.json'), 'utf8')).version;
+  const identity = process.env.HOMIE_APPLE_IDENTITY || '';
+  const profile = process.env.HOMIE_APPLE_NOTARY_PROFILE || '';
+  const sign = platform === 'darwin' && Boolean(identity);
+  const adhoc = identity === '-';
+  const notarize = sign && !adhoc && Boolean(profile);
+  const icon = { darwin: join(here, 'icons', 'icon.icns'), win32: join(here, 'icons', 'icon.ico') }[platform];
+  const entitlements = join(here, 'entitlements.mac.plist');
+  const staging = join(here, 'out', `.pack-${FOLDER[platform]}-${kind}`);
+  rmSync(staging, { recursive: true, force: true });
+  const [made] = await packager({
+    // The file's name is the game's name made safe for every file system (the toolkit's fileName). macOS shows that
+    // name in the menu bar and the Dock too (the packager writes it over any other); the window's title is the game's own.
+    dir: join(here, 'electron'), out: staging, name: meta.fileName, executableName: platform === 'darwin' ? undefined : meta.name,
+    platform, arch, electronVersion: electron, overwrite: true, asar: false, prune: true, quiet: true,
+    appBundleId: app.appId, appVersion: meta.version, buildVersion: String(app.build ?? 1), appCopyright: meta.author ? `© ${meta.author}` : undefined,
+    appCategoryType: 'public.app-category.games',
+    // Where Electron's own download is kept between builds: its usual cache, or the folder Electron's installer is told.
+    ...(process.env.electron_config_cache ? { download: { cacheRoot: process.env.electron_config_cache } } : {}),
+    ...(icon && existsSync(icon) ? { icon } : {}),
+    ...(platform === 'win32' ? { win32metadata: { CompanyName: meta.author ?? '', ProductName: meta.productName, FileDescription: meta.productName } } : {}),
+    ...(sign ? { osxSign: { identity, ...(adhoc ? { identityValidation: false } : {}), optionsForFile: () => ({ hardenedRuntime: true, ...((app.steam || adhoc) && existsSync(entitlements) ? { entitlements } : {}) }) } } : {}),
+    ...(notarize ? { osxNotarize: { keychainProfile: profile } } : {}),
+  });
+  if (!made) throw new Error('the packager made nothing');
+  const out = join(here, 'out', FOLDER[platform], kind);
+  rmSync(out, { recursive: true, force: true });
+  mkdirSync(dirname(out), { recursive: true });
+  renameSync(made, out);
+  rmSync(staging, { recursive: true, force: true });
+  // What is really there, by looking: never a name worked out from the game's.
+  const names = readdirSync(out);
+  const bundle = platform === 'darwin' ? names.find((n) => n.endsWith('.app')) : null;
+  const exe = platform === 'darwin' ? (bundle ? join(out, bundle, 'Contents', 'MacOS', readdirSync(join(out, bundle, 'Contents', 'MacOS'))[0]) : null) : join(out, platform === 'win32' ? `${meta.name}.exe` : meta.name);
+  if (!exe || !existsSync(exe)) throw new Error(`the packager finished, and the app's program is not where it should be in ${out}`);
+  // What was asked of the signer and the notary is one thing; what the finished app answers is what gets said.
+  const checks = {};
+  const ask = (name, cmd, args) => { try { execFileSync(cmd, args, { stdio: 'pipe', timeout: 60_000 }); checks[name] = true; } catch (error) { checks[name] = false; checks[`${name}Says`] = String(error?.stderr ?? error?.message ?? '').trim().split('\n').slice(-2).join(' ').slice(0, 300); } };
+  if (sign && bundle) ask('signature', 'codesign', ['--verify', '--deep', '--strict', join(out, bundle)]);
+  if (notarize && bundle) ask('stapled', 'xcrun', ['stapler', 'validate', join(out, bundle)]);
+  say({ ok: true, platform, arch, kind, path: out, app: bundle ? join(out, bundle) : out, exe, electron, signed: sign && checks.signature === true, adhoc, notarizeAsked: notarize, notarized: notarize && checks.stapled === true, checks });
+} catch (error) {
+  say({ ok: false, why: String(error?.message ?? error).split('\n').slice(0, 6).join(' ').slice(0, 800) });
+  process.exitCode = 1;
+}

package/standalone/shell/index.html

@@ -0,0 +1,36 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover, user-scalable=no">
+<title>Game</title>
+<link rel="stylesheet" href="shell.css">
+</head>
+<body>
+<iframe class="game" title="Game" allow="fullscreen; autoplay; gamepad"></iframe>
+<div class="room at-top-right" data-room-ui>
+  <button class="pill" type="button" data-share-toggle aria-expanded="false" aria-controls="share-sheet" aria-label="Room and invite"><svg viewBox="0 0 24 24" aria-hidden="true" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="18" cy="5.5" r="2.5"/><circle cx="6" cy="12" r="2.5"/><circle cx="18" cy="18.5" r="2.5"/><path d="m8.2 10.8 7.6-4.1M8.2 13.2l7.6 4.1"/></svg><span data-room-code>Finding a room…</span></button>
+  <div class="sheet" id="share-sheet" role="dialog" aria-label="This room" data-share-sheet hidden>
+    <div class="code"><b data-room-label>Offline</b><span data-room-state></span></div>
+    <div class="acts">
+      <button type="button" class="primary" data-invite>Invite</button>
+      <button type="button" data-quick>Quick play</button>
+    </div>
+    <span class="link" data-room-link></span>
+    <form class="join" data-join-form>
+      <input type="text" data-join-code inputmode="latin" autocomplete="off" autocapitalize="off" spellcheck="false" maxlength="32" placeholder="Room code" aria-label="Room code">
+      <button type="submit">Join a room</button>
+    </form>
+    <div class="foot"><button type="button" data-private>New private room</button><button type="button" data-offline>Play offline</button></div>
+  </div>
+</div>
+<div class="toast" data-toast role="status" hidden></div>
+<div class="notice" data-notice role="alertdialog" aria-modal="true" hidden>
+  <div class="box"><h1 data-notice-title></h1><p data-notice-text></p>
+    <div class="acts"><button type="button" class="primary" data-notice-quick>Quick play</button><button type="button" data-notice-offline>Play offline</button></div>
+  </div>
+</div>
+<script src="config.js"></script>
+<script src="shell.js"></script>
+</body>
+</html>