@v12-engine/create 0.1.1 → 0.4.0

package/README.md

@@ -1,5 +1,7 @@
 # @v12-engine/create
 
+> **Alpha.** V12 is in active development: APIs, file formats and saves can change between releases. Pin an exact version for anything you ship. Docs: https://v12-docs.vercel.app
+
 A project to start a game from, made with V12: its rules, its page, and the parts you choose.
 
 ```sh
@@ -13,12 +15,13 @@ It asks where to make it, which starter, what the game is called, which parts it
 | `empty`    | Hello world: a flat field and a scout to walk it. The default.                               |
 | `melee`    | A whole RTS: two races and their heroes, bases and armies, against the computer.             |
 | `campaign` | A campaign of three missions with a hero carried between them, drawn with the shared models. |
+| `examples` | What the engine can do, a small scene each, browsed from a list as three.js's examples are.  |
 
 ```sh
 npm create @v12-engine arena -- --yes --starter melee --server rooms --ratings
 ```
 
-The parts: the map editor (`--no-editor`), a server of one game, of many games in rooms, or none (`--server single|rooms|none`), ratings (`--ratings`), a test of the rules (`--no-tests`), a git repository (`--no-git`), and installing at once (`--install`).
+The parts: the map editor (`--no-editor`), a server of one game, of many games in rooms, or none (`--server single|rooms|none`), ratings (`--ratings`), a test of the rules (`--no-tests`), the shared art (`--no-assets`), a desktop app in an Electron shell (`--desktop`: `npm run app` opens it, `npm run package` makes the app to hand out), a git repository (`--no-git`), and installing at once (`--install`).
 
 In code: `createProject(folder, options)` from `@v12-engine/create`.
 

package/base/_gitignore

@@ -4,6 +4,11 @@ dist
 .DS_Store
 # the replays Play here keeps with a map: the designer's own, not the map's
 **/*.files/replays/
+# @if desktop
+# the app made to hand out (`npm run package`), and the shell's addon, compiled from its source on macOS
+out
+electron/presentation.node
+# @end
 # @if ratings
 # what the server keeps of who played: not code
 ratings.json

package/base/package.json

@@ -11,9 +11,9 @@
 	"dependencies": {
 		"@v12-engine/engine": "^0.0.0",
 		"@v12-engine/client": "^0.0.0",
-		"@babylonjs/core": "^9.31.0",
-		"@babylonjs/gui": "^9.31.0",
-		"@babylonjs/loaders": "^9.31.0"
+		"@babylonjs/core": "~9.31.0",
+		"@babylonjs/gui": "~9.31.0",
+		"@babylonjs/loaders": "~9.31.0"
 	},
 	"devDependencies": {
 		"@types/node": "^26.6.5",

package/base/src/main.ts

@@ -13,24 +13,32 @@
  * the top bar, Alt+Shift+D) and its cheats are in the game while developing (`npm run dev`), not in a built page:
  * `debug` says otherwise
  */
+// @if !desktop
 import { appScenes, sceneAsked, startApp } from '@v12-engine/client/app'
+// @end
+// @if desktop
+import { appScenes, exitButton, sceneAsked, startApp } from '@v12-engine/client/app'
+// @end
 import '@v12-engine/client/styles.css'
 // the theme's typefaces come with the client: the page's own font stays what it was
 import '@v12-engine/client/fonts.css'
 // @if editor
 import { editor } from './editor'
 // @end
-import { DEFAULT_MAP, maps } from './maps'
-import { rules, start } from './rules'
+import { game } from './game'
+// @if desktop
+// what the desktop app adds: its shell's stores, the game saved as the window closes, an error log, updates, Exit
+import { desktop } from './desktop'
+// @end
 
+// @if desktop
+const shell = desktop()
+
+// @end
 const scenes = appScenes({
-	// the game's code (its looks, and the client that draws them) fetched as a scene first plays it: the start screen
-	// shows at once, its rules telling it what to say of the game
-	game: () => import('./game').then((module) => module.game),
-	rules,
-	maps,
-	map: DEFAULT_MAP,
-	start,
+	// the game (`src/game.ts`): its rules say what the start screen shows, its maps and its start are the scenes', and its
+	// look (and the client that draws it) is fetched as a scene first plays it, so that the start screen shows at once
+	game,
 	// @if editor
 	editor,
 	// @end
@@ -44,7 +52,17 @@ const scenes = appScenes({
 	// the random map's preview made in a worker of the page's (`src/generate.worker.ts`): the menu goes on while it is made
 	generatorWorker: () => new Worker(new URL('./generate.worker.ts', import.meta.url), { type: 'module' }),
 	// @end
+	// @if desktop
+	// the game saved from its pause menu, as files, and as the window closes
+	saves: {},
+	// @end
+	// @if !desktop
 	menu: { description: 'A game made with V12.' },
+	// @end
+	// @if desktop
+	// Exit, last on the start screen: in the shell alone, as a page cannot close its tab
+	menu: { description: 'A game made with V12.', buttons: [exitButton(shell)] },
+	// @end
 	// the Credits on the start screen (`creditsScene`): who made the game, by parts, scrolling
 	credits: {
 		sections: [
@@ -56,6 +74,14 @@ const scenes = appScenes({
 
 /** The ground's textures made in a worker of the page's (`src/ground.worker.ts`), made at the first texture: the page goes on while they are made */
 const groundWorker = () => new Worker(new URL('./ground.worker.ts', import.meta.url), { type: 'module' })
+/** The navigations of its worlds built in another (`src/navigation.worker.ts`), made at the first build */
+const navigationWorker = () => new Worker(new URL('./navigation.worker.ts', import.meta.url), { type: 'module' })
 
-const app = startApp({ target: '#game', title: rules.name, scenes, start: sceneAsked(scenes, 'home'), groundWorker })
+// @if !desktop
+const app = startApp({ target: '#game', game, scenes, start: sceneAsked(scenes, 'home'), groundWorker, navigationWorker })
+// @end
+// @if desktop
+const app = startApp({ target: '#game', game, scenes, start: sceneAsked(scenes, 'home'), groundWorker, navigationWorker, ...shell.options })
+shell.started(app)
+// @end
 Object.assign(window, { app })

package/base/src/navigation.worker.ts

@@ -0,0 +1,7 @@
+/**
+ * The page's worker that builds the navigations of its worlds, so the page goes on while a large map is made. Given to the
+ * app in `main.ts` (`navigationWorker`)
+ */
+import { serveNavigationBuilds } from '@v12-engine/engine'
+
+serveNavigationBuilds()

package/base/vite.config.ts

@@ -1,4 +1,4 @@
-// @if editor|assets
+// @if editor|assets|desktop
 import { defineConfig } from 'vite'
 // @if assets
 import { assetsPackage } from '@v12-engine/client/vite'
@@ -8,6 +8,13 @@ import { editorFiles } from '@v12-engine/editor/vite'
 // @end
 
 export default defineConfig({
+	// @if desktop
+	// the app made to hand out is not the page's to watch
+	server: { watch: { ignored: ['**/out/**'] } },
+	// the shell's own Chromium (Electron's) is the one browser the built page runs in
+	build: { target: 'esnext' },
+	// @end
+	// @if editor|assets
 	plugins: [
 		// @if assets
 		// the shared art (@v12-engine/assets) served where the game's shared files are (/models/…), behind public/: a file
@@ -18,8 +25,23 @@ export default defineConfig({
 		// @if editor
 		// the map editor keeps the game's maps in the project through the dev server: Save writes them into `src/maps`.
 		// Only in `npm run dev`; a built page keeps maps in the browser
-		editorFiles({ gameFolder: () => 'src' }),
+		editorFiles({
+			gameFolder: () => 'src',
+			// where New with code in the editor may write a stub (never over a file)
+			scaffold: ['src'],
+			// the scripts the editor's Run panel may start and stop while developing, and no others
+			run: [
+				// @if server
+				'server',
+				// @end
+				// @if desktop
+				// (`app` starts the dev server itself, which the editor is open on: this one uses that one)
+				'app:editor',
+				// @end
+			]
+		}),
 		// @end
 	]
+	// @end
 })
 // @end

package/cli.mjs

@@ -30,9 +30,13 @@ const DEFAULT_FOLDER = 'my-game'
 const PARTS = {
 	editor: 'the map editor, at /?editor, saving maps into the project',
 	tests: 'a test of the rules with no page, in Vitest',
-	assets: 'shared models to start with (@v12-engine/assets): adventurers with their clips, buildings, trees and rocks, props, weapons'
+	assets: 'shared models to start with (@v12-engine/assets): adventurers with their clips, buildings, trees and rocks, props, weapons',
+	desktop: 'a desktop app: the page in a window of its own, an Electron shell in electron/: npm run app'
 }
 
+/** The parts a project has when nobody says: every part but the desktop app, whose shell (Electron) is some 100 to 260 MB to fetch */
+const DEFAULT_PARTS = ['editor', 'tests', 'assets']
+
 /** What each kind of server is, for the help and the question */
 const SERVER_KINDS = {
 	single: 'one game at a time, joined from the page at /?server',
@@ -53,7 +57,7 @@ ${Object.entries(SERVER_KINDS)
 With no flags it asks for what it needs. With --yes, or where nobody can answer
 (CI, a pipe), it asks nothing and takes the defaults for what it was not told:
 the empty starter, the editor, a single server with no ratings, the tests, the
-shared art, a git repository, and no install.
+shared art, no desktop app, a git repository, and no install.
 
 Examples:
   npm create @v12-engine                         ask for everything
@@ -62,6 +66,7 @@ Examples:
   npm create @v12-engine . -- --starter melee --name "Orc Wars"
   npm create @v12-engine duel -- -y --server none --no-editor --install
   npm create @v12-engine arena -- -y --starter melee --server rooms --ratings
+  npm create @v12-engine quest -- -y --desktop      a desktop app too (Electron)
   npx create-v12 apps/orc-wars -y --source in the library's own repository
   npx @v12-engine/create --list                  the starters
 
@@ -114,7 +119,9 @@ export function program(act) {
 		.option('--tests', `with ${PARTS.tests}`)
 		.option('--no-tests', 'without it')
 		.option('--assets', `with ${PARTS.assets}`)
-		.option('--no-assets', 'without it (melee and the campaign cannot be made without it)')
+		.option('--no-assets', 'without it (melee, the campaign and the examples need it)')
+		.option('--desktop', `with ${PARTS.desktop}`)
+		.option('--no-desktop', 'without it')
 		.option('--git', 'make it a git repository, with a first commit (not inside one)')
 		.option('--no-git', 'no repository')
 		.option('--source', "read the library as it is written: for a project inside the library's own repository (apps/), to work on both at once")
@@ -183,7 +190,8 @@ export async function run(argv, { ask = canAsk(), prompts = clack, log = console
 		const plays = [
 			'The page plays it',
 			project.editor && '/?editor is its map editor',
-			project.server === 'rooms' && '/?find-game finds games on its server'
+			project.server === 'rooms' && '/?find-game finds games on its server',
+			project.desktop && `${words.run('app')} opens it in a window of its own`
 		]
 			.filter(Boolean)
 			.join('; ')
@@ -221,6 +229,7 @@ export function decide(folder, flags) {
 		ratings: flags.ratings ?? false,
 		tests: flags.tests ?? true,
 		assets: assetsOf(flags.starter ?? DEFAULT_STARTER, flags.assets),
+		desktop: flags.desktop ?? false,
 		source: flags.source ?? false,
 		git: flags.git ?? !insideRepository(where),
 		install: flags.install ?? false,
@@ -267,14 +276,19 @@ async function askFor(folder, flags, prompts) {
 			))
 		// a starter that cannot be made without the shared art has it, and is not asked
 		const needed = starterNamed(starter).needs?.includes('assets')
-		const parts = { editor: flags.editor, tests: flags.tests, assets: needed ? assetsOf(starter, flags.assets) : flags.assets }
+		const parts = {
+			editor: flags.editor,
+			tests: flags.tests,
+			assets: needed ? assetsOf(starter, flags.assets) : flags.assets,
+			desktop: flags.desktop
+		}
 		const unsaid = Object.keys(PARTS).filter((part) => parts[part] === undefined)
 		if (unsaid.length) {
 			const chosen = await answer(
 				prompts.multiselect({
 					message: 'What should it have? (space to choose, enter when done)',
 					options: unsaid.map((part) => ({ value: part, label: part, hint: PARTS[part] })),
-					initialValues: unsaid,
+					initialValues: unsaid.filter((part) => DEFAULT_PARTS.includes(part)),
 					required: false
 				})
 			)
@@ -312,6 +326,7 @@ async function askFor(folder, flags, prompts) {
 			ratings,
 			tests: parts.tests,
 			assets: parts.assets,
+			desktop: parts.desktop,
 			source: flags.source ?? false,
 			git,
 			install,

package/index.mjs

@@ -3,7 +3,7 @@
  * N2), each a folder of files laid over the ones before:
  *
  * 1. `base/`: what every project has: its page, its `package.json`, its TypeScript config
- * 2. `layers/<option>/`: what an option on adds (the editor, a server, the tests), in `LAYERS`'s order
+ * 2. `layers/<option>/`: what an option on adds (the editor, a server, the tests, a desktop app), in `LAYERS`'s order
  * 3. `starters/<starter>/`: the game, its rules, look and maps, and its README
  * 4. `starters/<starter>/layers/<option>/`: what the starter adds with an option on (its tests)
  *
@@ -60,14 +60,14 @@ export function titleProblem(title) {
  * The options that are layers, in the order they are laid: each may have a folder in `layers/` and in a starter's
  * `layers/`, and is a name its files' `@if` lines may ask about
  */
-export const LAYERS = ['editor', 'server', 'rooms', 'tests', 'assets', 'source']
+export const LAYERS = ['editor', 'server', 'rooms', 'tests', 'assets', 'desktop', 'source']
 
 /**
  * What a file's `@if` lines may ask about: the layers, and what changes a few lines and has no files of its own
  * (`ratings`; `single`, a server of one game at a time, where `server` is any server and `rooms` one of rooms;
  * `generator`, the starter's, not the command line's: its random map made in a worker, `starters`)
  */
-export const OPTIONS = ['editor', 'server', 'single', 'rooms', 'ratings', 'tests', 'assets', 'source', 'generator']
+export const OPTIONS = ['editor', 'server', 'single', 'rooms', 'ratings', 'tests', 'assets', 'desktop', 'source', 'generator']
 
 /** What a server of the game is: one game at a time (`single`), many games in rooms that players find and make (`rooms`), or none */
 export const SERVERS = ['single', 'rooms', 'none']
@@ -91,10 +91,13 @@ export function commandsOf(packageManager = 'npm') {
 	return { install, run }
 }
 
-/** The files whose words may be the game's name and may have `@if` lines: its code, its page, its README, its maps */
+/** The files whose words may be the game's name and may have `@if` lines: its code, its page, its README, its maps, its shell's main process */
 const TEXT = new Set(['.ts', '.mjs', '.html', '.md', '.json', '.css'])
 const isText = (path) => TEXT.has(extname(path)) || basename(path) === '_gitignore'
 
+/** The order of the keys of a project's `package.json`: the rest after, as they came */
+const TOP = ['name', 'private', 'version', 'type', 'main']
+
 /** The order of a project's scripts, as one reads them: the rest after, as they came */
 const SCRIPTS = ['dev', 'build', 'preview', 'server', 'test', 'typecheck']
 
@@ -111,6 +114,9 @@ const SCRIPTS = ['dev', 'build', 'preview', 'server', 'test', 'typecheck']
  * - `assets`: the shared art (`@v12-engine/assets`: models only: adventurers with their clips, buildings, trees and rocks, props, weapons), served by the dev server and
  *   copied into a build as the game uses it (`assetsPackage`); on when left out, and always for a starter that plays
  *   with it (`needs`)
+ * - `desktop`: the page as a desktop app, in an Electron shell (`electron/`, `npm run app`, `npm run package`): the dev
+ *   server on the port the shell opens, and the page built for the shell's Chromium. Off when left out: Electron is
+ *   some 100 to 260 MB, fetched the first time the app is opened
  * - `packageManager`: what installs and runs it (`PACKAGE_MANAGERS`): its README and comments say its words; `npm`
  *   when left out
  * - `source`: the library read as it is written, for a project inside the library's own repository (`apps/`): its
@@ -128,6 +134,7 @@ export async function createProject(folder, options = {}) {
 		editor = true,
 		server = 'single',
 		tests = true,
+		desktop = false,
 		source = false,
 		packageManager = 'npm',
 		dependencies = {}
@@ -146,7 +153,18 @@ export async function createProject(folder, options = {}) {
 	const problem = titleProblem(title)
 	if (problem) throw new Error(`"${title}": ${problem}`)
 	const generator = !!starterNamed(starter).generator
-	const on = { editor, server: server !== 'none', single: server === 'single', rooms: server === 'rooms', ratings, tests, assets, source, generator }
+	const on = {
+		editor,
+		server: server !== 'none',
+		single: server === 'single',
+		rooms: server === 'rooms',
+		ratings,
+		tests,
+		assets,
+		desktop,
+		source,
+		generator
+	}
 	// the way from the project to the repository's root (`{{root}}` in the source layer): this package is `packages/create` of it
 	const root = relative(where, resolve(here, '../..')).split(sep).join('/') || '.'
 	const files = await putTogether(starter, on)
@@ -183,7 +201,7 @@ export async function createProject(folder, options = {}) {
 				: content
 		)
 	}
-	return { name, title, where, starter, editor, server, ratings, tests, assets, source, packageManager }
+	return { name, title, where, starter, editor, server, ratings, tests, assets, desktop, source, packageManager }
 }
 
 /**
@@ -264,7 +282,9 @@ function merged(before, layer) {
 	for (const key of ['dependencies', 'devDependencies']) {
 		if (project[key]) project[key] = Object.fromEntries(Object.entries(project[key]).sort(([a], [b]) => a.localeCompare(b)))
 	}
-	return `${JSON.stringify(project, null, '\t')}\n`
+	// what a layer adds at the top (the desktop app's `main`) where one reads it, before the scripts
+	const top = (key) => (TOP.includes(key) ? TOP.indexOf(key) : TOP.length)
+	return `${JSON.stringify(Object.fromEntries(Object.entries(project).sort(([a], [b]) => top(a) - top(b))), null, '\t')}\n`
 }
 
 /** The starters' game is `my-game`, My game: the project's is its own, in its code, its page, its README and its maps */

package/layers/desktop/electron/app.mjs

@@ -0,0 +1,237 @@
+// The shell: a window with the page in it. Its full screen is the game's, on macOS a plain window over the screen
+// (`setSimpleFullScreen`), no Space (`fullscreenable: false`), and the Dock and the menu bar hidden by the app's
+// presentation options, which Electron's API has no way to say: the small addon `presentation.m` says them
+// (`npm run app` and `npm run package` compile it). Without the addon the bars auto-hide, as `setSimpleFullScreen` leaves
+// them. Esc is then a key of the page's, the game's pause menu. Elsewhere it is the window's own full screen.
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { app, autoUpdater, BrowserWindow, ipcMain, Menu, protocol, shell } from 'electron'
+import { IDENTIFIER, NAME, UPDATES } from './config.mjs'
+import { logFiles, recordFiles } from './files.mjs'
+import { answer, contentPolicy } from './serve.mjs'
+import { feedOf, updatesOf } from './updates.mjs'
+
+const here = dirname(fileURLToPath(import.meta.url))
+
+/** `NSApplicationPresentationHideDock | NSApplicationPresentationHideMenuBar` */
+export const HIDE_BARS = 0x2 | 0x8
+/** How long the page has to save the game as the window closes, past which the window closes anyway */
+const CLOSE_WITHIN = 6000
+/** What AppKit's move of the window over the screen and back takes, and a little */
+const ANIMATION = 600
+
+// (before the app is ready, as the scheme has to be: `app:` is a page's origin like `https:`)
+protocol.registerSchemesAsPrivileged([
+	{ scheme: 'app', privileges: { standard: true, secure: true, supportFetchAPI: true, stream: true, codeCache: true } }
+])
+
+/** The addon, where it is built and the system is macOS */
+export function presentation() {
+	const file = join(here, 'presentation.node')
+	if (process.platform !== 'darwin' || !existsSync(file)) return undefined
+	try {
+		return createRequire(import.meta.url)(file)
+	} catch (error) {
+		console.error('The presentation options cannot be said:', error)
+		return undefined
+	}
+}
+
+/**
+ * Starts the shell. `main.mjs` gives no option but `page` while developing; the rest are for checks of the shell
+ * (`apps/desktop/measure`). `page`: the dev server's address, in the place of the built page. `dist`: the built page.
+ * `query`: what its address asks. `connect`: other addresses its policy lets it ask. `window`: said over the window's
+ * options. `over`: whether it starts over the screen. `userData`: the app's folder. `prepared`: told of the window
+ * before the page is asked for
+ */
+export async function startShell(options = {}) {
+	const { page, dist = join(here, '..', 'dist'), query = '', connect = [], window: asked = {}, over: startsOver = true, userData, prepared } = options
+	app.setName(NAME)
+	app.setPath('userData', userData ?? join(app.getPath('appData'), IDENTIFIER))
+	await app.whenReady()
+
+	// the keys a player expects of the system, and none of the browser's (reload, its tools, its full screen) but while developing
+	Menu.setApplicationMenu(
+		Menu.buildFromTemplate([{ role: 'appMenu' }, { role: 'editMenu' }, ...(page ? [{ role: 'viewMenu' }] : []), { role: 'windowMenu' }])
+	)
+	const policy = contentPolicy(connect)
+	protocol.handle('app', (request) => answer(dist, request, policy))
+	/** Whether an address is the page's own: the app's scheme, or the dev server's (Node's URL gives a scheme of its own no origin) */
+	const ours = (address) => (page ? new URL(address).origin === new URL(page).origin : new URL(address).protocol === 'app:')
+
+	const records = recordFiles(app.getPath('userData'))
+	const logs = logFiles(app.getPath('logs'))
+	const native = presentation()
+	const sizeFile = join(app.getPath('userData'), 'window.json')
+	const kept = readKept(sizeFile)
+	const updates = updatesOf(autoUpdater, feedOf(UPDATES), app.isPackaged)
+
+	const win = new BrowserWindow({
+		width: kept?.width ?? 1280,
+		height: kept?.height ?? 800,
+		...(kept && { x: kept.x, y: kept.y }),
+		useContentSize: true,
+		minWidth: 960,
+		minHeight: 600,
+		title: NAME,
+		show: false,
+		// AppKit's own way in (the green button, Ctrl+Cmd+F): a Space, with the bars back at its edges, would be a second full screen
+		fullscreenable: process.platform !== 'darwin',
+		backgroundColor: '#000000',
+		// (macOS takes the bundle's; Windows and Linux the window's)
+		...(process.platform !== 'darwin' && { icon: join(here, 'icons/icon.png') }),
+		webPreferences: { preload: join(here, 'preload.cjs'), contextIsolation: true, sandbox: true, nodeIntegration: false },
+		...asked
+	})
+
+	let over = false
+	/** The window's place while it is over the screen */
+	let windowed
+	let closing = false
+	let closeIsHeard = false
+
+	/** The window's size and place kept for the next start: a window's, never the screen's */
+	const keep = () => {
+		if (over || win.isDestroyed()) return
+		try {
+			mkdirSync(dirname(sizeFile), { recursive: true })
+			writeFileSync(sizeFile, JSON.stringify(win.getContentBounds()))
+		} catch (error) {
+			console.error('The window size cannot be kept:', error)
+		}
+	}
+
+	const hideBars = () => {
+		if (over) native?.setOptions(HIDE_BARS)
+	}
+
+	const setOver = (on) => {
+		if (on === over) return
+		if (on) {
+			keep()
+			windowed = win.getContentBounds()
+		}
+		over = on
+		if (process.platform === 'darwin') {
+			win.setSimpleFullScreen(on)
+			hideBars()
+			// (the window's style changes under the page, which is left without the keyboard: read back `document.hasFocus()` false)
+			win.webContents.focus()
+			setTimeout(() => win.isDestroyed() || win.webContents.focus(), ANIMATION)
+			// (AppKit animates the way there, and a way back asked during it ends at a size of its own: the size is put back when it is done)
+			if (!on && windowed) {
+				const back = windowed
+				setTimeout(() => over || win.isDestroyed() || win.setContentBounds(back), ANIMATION)
+			}
+		} else {
+			win.setFullScreen(on)
+		}
+	}
+
+	win.on('focus', hideBars)
+	win.on('resize', () => win.webContents.send('v12:resized'))
+	win.on('close', (event) => {
+		keep()
+		if (closing || !closeIsHeard) return
+		// held until the page has saved the game: it destroys the window, or the time is up
+		event.preventDefault()
+		closing = true
+		win.webContents.send('v12:close-requested')
+		setTimeout(() => win.isDestroyed() || win.destroy(), CLOSE_WITHIN).unref()
+	})
+	app.on('window-all-closed', () => app.quit())
+
+	// a question is the app's own page's, and only that
+	const own = (event) => {
+		try {
+			return ours(event.senderFrame?.url ?? 'about:blank')
+		} catch {
+			return false
+		}
+	}
+	const allowed =
+		(handler) =>
+		(event, ...rest) => {
+			if (!own(event)) throw new Error('Asked by something other than the page of the app')
+			return handler(...rest)
+		}
+	ipcMain.handle(
+		'v12:fullscreen',
+		allowed((on) => {
+			if (typeof on === 'boolean') setOver(on)
+			return over
+		})
+	)
+	ipcMain.handle(
+		'v12:close',
+		allowed(() => win.close())
+	)
+	ipcMain.handle(
+		'v12:destroy',
+		allowed(() => win.destroy())
+	)
+	ipcMain.handle(
+		'v12:records',
+		allowed((action, ...rest) => {
+			if (!Object.hasOwn(records, action)) throw new Error(`Nothing is called ${action}`)
+			return records[action](...rest)
+		})
+	)
+	ipcMain.handle(
+		'v12:log',
+		allowed((action, ...rest) => {
+			if (!Object.hasOwn(logs, action)) throw new Error(`Nothing is called ${action}`)
+			return logs[action](...rest)
+		})
+	)
+	ipcMain.handle(
+		'v12:open-folder',
+		allowed(async (folder) => {
+			if (folder !== 'saves' && folder !== 'logs') throw new Error(`"${folder}" is not a folder of the app's`)
+			const path = folder === 'logs' ? app.getPath('logs') : join(app.getPath('userData'), 'saves')
+			mkdirSync(path, { recursive: true })
+			await shell.openPath(path)
+		})
+	)
+	ipcMain.handle(
+		'v12:update-check',
+		allowed(() => updates.check())
+	)
+	ipcMain.handle(
+		'v12:update-install',
+		allowed(() => {
+			// the page saved the game before it asked: the window is not held again
+			closing = true
+			updates.install()
+		})
+	)
+	ipcMain.on('v12:close-is-heard', (event, heard) => {
+		if (own(event)) closeIsHeard = heard === true
+	})
+
+	// the page stays where it is: another address is for the player's browser, or for nothing
+	win.webContents.on('will-navigate', (event, url) => {
+		if (!ours(url)) event.preventDefault()
+	})
+	win.webContents.setWindowOpenHandler(() => ({ action: 'deny' }))
+
+	prepared?.(win)
+	if (startsOver) setOver(true)
+	const shown = new Promise((resolve) => win.webContents.once('did-finish-load', resolve))
+	await win.loadURL(page ? new URL(query, page).href : `app://game/${query}`)
+	await shown.catch(() => undefined)
+	if (!asked.paintWhenInitiallyHidden) win.show()
+	hideBars()
+	return { win, native, setOver, isOver: () => over }
+}
+
+function readKept(file) {
+	try {
+		const kept = JSON.parse(readFileSync(file, 'utf8'))
+		return Number.isFinite(kept.width) && Number.isFinite(kept.height) ? kept : undefined
+	} catch {
+		return undefined
+	}
+}

package/layers/desktop/electron/config.mjs

@@ -0,0 +1,16 @@
+// What the app is called and where it keeps its things: yours to settle before it is handed out. The identifier names
+// the app's folder of the system (`~/Library/Application Support/<identifier>`, `%APPDATA%\<identifier>`): changing it
+// after a release leaves the players' saves in the old one. The version is the project's `package.json`'s.
+
+/** The app's name, on its window, its menu and its bundle */
+export const NAME = 'My game'
+
+/** The app's identifier: its bundle's on macOS, and its data folder's name everywhere */
+export const IDENTIFIER = 'com.example.my-game'
+
+/**
+ * Where its releases are, for the updater (`updates.mjs`): a folder of static files by system and processor, as
+ * Electron's docs lay it out (`<address>/darwin/arm64/RELEASES.json`, `<address>/win32/x64/RELEASES`). A placeholder,
+ * which asks nothing: a host under `.invalid` is never asked. `docs/scenes/desktop.md`, Updates, says what goes here
+ */
+export const UPDATES = 'https://updates.invalid/REPLACE-WITH-THE-ADDRESS'