homegames-common 1.7.0 → 1.7.2

package/docs/homegames-context.md

@@ -2,7 +2,7 @@
 
 > Grounding reference for Homegames platform questions and SquishJS game authoring. **Part I** describes the product and implementation; **Part II** describes the game contract, including differences between portable projects and the retained hosted publishing path.
 >
-> **Implementation review: October 11, 2026.** This describes the current local working-tree code, including portable Studio, exports, browser saves and RTC. It does not establish what homegames.io has deployed. Existing downloaded HTML files retain the runtime bundled when they were exported.
+> **Implementation review: October 16, 2026.** This describes the current local working-tree code, including portable Studio, exports, browser saves and RTC. It does not establish what homegames.io has deployed. Existing downloaded HTML files retain the runtime bundled when they were exported.
 
 ---
 
@@ -88,10 +88,11 @@ These are three different kinds of persistence:
 
 | Data | Current local-first storage | Portable backup |
 | --- | --- | --- |
-| Draft source and authored media | Studio IndexedDB project library | Project `.zip` or playable `.html` |
-| Named source snapshots | Immutable versions in that browser's library | Export the selected version; history is not included |
+| Saved source and authored media | Studio IndexedDB project library after explicit Save | Project `.zip`, playable `.html`, or full Studio backup |
+| Source snapshots | Every explicit Save adds an immutable History entry | Full Studio backup includes history; individual game exports do not |
 | Game progress | Installation-scoped IndexedDB saves, when the game calls `saveGame` | Download save / Load save JSON |
 
+Unsaved source stays in memory until Save; a full Studio backup also captures that working copy.
 No account or cloud sync is involved. Clearing/evicting browser storage can lose
 projects and progress. Optional persistent-storage permission is best-effort;
 keep file backups. Importing a ZIP makes a new installation, and each newly
@@ -112,30 +113,35 @@ The local-first implementation is integrated into the **existing Studio**, using
 its editor, file tree, tabs, preview and asset tools. `studio-local.html` redirects
 there; it is not a separate product.
 
-- **New game:** the ten original templates (blank, click, keyboard, multiplayer,
-  text input, image upload, animation, scrolling world, buttons, glow & fade), plus
-  Pocket Chime. Templates are static portable ZIPs; no API/account request is needed.
-- **My Games / Import ZIP:** projects live in `homegames-studio-projects` IndexedDB
-  (schema v2). Imports validate bytes without executing code. Each import has a
-  fresh local installation identity. Previous guest-draft recovery preserves edits;
-  it is not a general hosted-project/asset migration tool.
-- **Editing:** draft source and binary files autosave locally, including incomplete
-  or invalid code. Play and export validate separately. Generation checks prevent
-  stale tabs overwriting newer edits; failed/quota-limited writes are visible.
-- **Versions:** Save snapshot creates a named immutable copy. Open snapshot previews
-  and exports that version read-only. Restore snapshot atomically backs up the
-  current draft before restoring source/assets. It does not roll back game progress.
-- **Assets:** uploads, drawing, recording and keyboard/audio tools write project
-  files, usually under `assets/`. Source references use project-relative paths.
-  These are different from session-only files chosen by a player during a game (§9).
-- **Preview / Share:** the game runs in an opaque sandboxed iframe with RTC and manual
-  invitations. The scene inspector and second simulated local preview player still
-  need integration with this isolated preview; real RTC guests are supported now.
-- **Export ZIP / HTML:** ZIP is a transparent, editable project archive. HTML is the
-  runnable browser copy. Source history and progress are separate from both exports.
-- **Guide:** this reference remains available for game authoring and external AI use.
-  Hosted publishing/settings/AI entry points are inactive in the local-first Studio;
-  `AI_FEATURES_ENABLED` is false. Legacy backend AI/docs handlers remain separate.
+- **Games:** opens a switcher over the main editor, with New game and Import game
+  (HTML or ZIP). Templates are static portable projects; no account is needed.
+- **Editing and Save:** edits remain in memory until explicit Save / Ctrl+S / Cmd+S.
+  Each successful Save atomically keeps source/media and adds an immutable History
+  snapshot. The optional save message names it; blank messages use Save N. Incomplete
+  code can be saved. Play, asset insertion and exports do not save the working copy.
+  Generation checks prevent stale tabs overwriting newer edits; failed writes keep
+  the working copy and message available for retry.
+- **History:** sits left of Files. Snapshots are read-only and can be played or exported.
+  Back to editing restores the in-memory working copy. Restore loads snapshot files
+  as unsaved edits; Save keeps them. Switching games or restoring over unsaved work
+  asks before discarding it. Source restoration does not roll back player progress.
+- **Assets:** a reusable browser library. Upload, Draw, Record and Keyboard keep
+  originals there. Add to game copies selected files into the current project;
+  Save keeps that project change. Authored references use relative asset paths,
+  not hosted IDs. Session uploads from players are a separate mechanism (§9).
+- **Preview:** Play runs current source in an isolated iframe. Options provides
+  inspection and a second local test player; Invite players connects real RTC guests.
+  Editing the source requires restarting Play to see the change.
+- **Export & share:** ZIP contains editable source/media; HTML is a playable copy.
+  Neither contains full source history or existing progress. Inviting players keeps
+  the running browser tab as host; Share a copy transfers a separate editable pack.
+- **Settings:** appearance, browser storage, and full-workspace backup/restore.
+  A .homegames-backup includes games, history, original assets, preview saves/exports,
+  preferences, and the current unfinished source without making an extra snapshot.
+  Restore replaces the workspace atomically and keeps an Undo last restore copy.
+- **Learn:** interactive examples, a getting-started tutorial, searchable API topics,
+  and task-oriented snippets with labeled insertion points. Copy full reference
+  keeps this document available for an external coding assistant.
 
 The isolated player cannot access the Studio's DOM or project storage. It receives
 only its project bytes and a private, installation-bound progress channel. This
@@ -265,8 +271,8 @@ account backend and publishing adds API/MongoDB/Forgejo/RabbitMQ/validation serv
   full **per-player view snapshots**, not deltas or the entire combined host tree.
   Identical frames can be skipped and queued obsolete frames coalesced.
 - Squish is the versioned binary node format. Default authoring target: `squish-142`
-  (`squishjs@1.4.2`). The browser bundle currently contains **142, 143 and 145**;
-  the shared Node loader map also contains **146**. The publish runner uses the
+  (`squishjs@1.4.2`). The browser bundle and shared Node loader currently contain
+  **142, 143, 145 and 146**. The publish runner uses the
   map included in its image. Do not infer browser support from Node availability;
   portable validation rejects unavailable/mismatched versions rather than substituting.
   References to 144-era APIs below describe behavior introduced then, not a bundled
@@ -478,6 +484,9 @@ class MyGame extends Game {
     // A player joined. info.name is their display name.
     handleNewPlayer({ playerId, info, settings, clientInfo }) {}
 
+    // A player changed their name in the player menu. Refresh their labels.
+    handlePlayerUpdate(playerId, { info, settings }) {}
+
     // A player left. Clean up their nodes/state.
     handlePlayerDisconnect(playerId) {}
 
@@ -553,6 +562,7 @@ constructor({ saveGame, saveData }) {
 
 **Method signatures are exact and important:**
 - `handleNewPlayer` receives a **single object** `{ playerId, info, settings, clientInfo, requestedGame }` — destructure it. `playerId` is a number. `info.name` is the player's name.
+- Players initially get a random two-word name. **More → Your name → Save name** changes it and remembers it in that browser. Local, RTC (including manual connections), and WebSocket sessions call `handlePlayerUpdate(playerId, { info, settings })` for a rename; `info.name` contains the new name and settings are preserved. Update any cached roster or label in this hook. Names are non-unique display text, 1–32 characters, never an identity or authorization key; use `playerId` for session state. Browser preferences stay outside game ZIPs/HTML, so recipients use their own names.
 - `handlePlayerDisconnect(playerId)` receives the **bare id**, not an object. (If a player id reconnects while already connected, the runtime fires `handlePlayerDisconnect` for the old connection and then `handleNewPlayer` again.)
 - `handleKeyDown(playerId, key)` / `handleKeyUp(playerId, key)` — two positional args.
 - A node's `onClick` receives `(playerId, x, y)` — see §9.
@@ -935,7 +945,7 @@ this.setTimeout(() => this.base.removeChild(sound.id), 250);
 
 The `assetInfo` key (`'potato'`, `'hiss'`) names a **logical entry in `metadata().assets`**, whose value loads bytes from a project path (portable) or hosted asset ID (legacy). Keep the key stable; it is not itself a database ID or a file path.
 
-> **Audio is deduped by asset KEY, not by node.** The client tracks playing sounds per key: two nodes with the same key play one sound, and a sound only restarts after its key has been absent from at least one rendered frame — a remove + re-add in the same tick won't re-trigger it, and a sound that finished playing won't replay while its node just sits in the tree. So the pattern is always **add to play, remove when done, re-add to replay**. Two platform behaviors games don't manage: browsers keep all audio silent until the player's first tap/click/keypress (autoplay policy — don't front-load a sound before any interaction), and players who mute sound in their settings simply don't get audio; games do nothing about either.
+> **Each audio node plays once.** The client tracks playback by node ID plus asset key. A fresh `GameNode.Asset` can replay the same clip; two separate nodes can play it at the same time. Leaving a finished node attached does not loop it. Remove old sound nodes to stop playback and avoid accumulating them; use a fresh node for the next play. Reusing the exact same node requires its sound to be absent from a rendered frame before it can restart. Start audio from a player action so browser autoplay rules allow it. Muted players do not hear audio.
 
 ### 7.3.1 Cropping an image / spritesheets (`squish-139`+)
 
@@ -1983,8 +1993,8 @@ Runtime:      one host-authoritative game instance: browser LocalSession (local
               Share/QR joins the running host; it sends views/media, not editable game source.
               Manual offer/answer bypasses Homegames signaling but cannot guarantee all NAT paths.
 Portable:     ordinary .zip = homegame.json + source + media + generated inventory; .html = playable copy.
-              default squish-142; browser supports 142/143/145; pin matching manifest/metadata/require.
-              Node map also has 146; that does not make it available in the browser bundle.
+              default squish-142; browser supports 142/143/145/146; pin matching manifest/metadata/require.
+              The publish runner must also contain the chosen version when using legacy publishing.
 Saves:        constructor({saveGame, saveData}); validate loaded JSON and rebuild nodes from state.
               Portable: <=1 MiB UTF-8 JSON; Promise resolves after IndexedDB commit, no write debounce.
               installation + save-schema:N slot; source snapshots don't roll back progress.
@@ -2021,8 +2031,8 @@ Nodes:        GameNode.Shape({ shapeType, coordinates2d, fill, color, border, on
               GameNode.Text({ textInfo:{ text,x,y,size,align,color,font }, playerIds })       // NO onClick
               GameNode.Asset({ coordinates2d, assetInfo:{ key:{pos:{x,y},size:{x,y},startTime} }, playerIds })  // clickable
               image drawn from assetInfo pos/size; clicks hit coordinates2d -> keep them aligned (§7.3)
-              audio = zero-size Asset; add to tree = play, remove = stop; deduped by KEY — the key must
-              leave a frame before it re-triggers (§7.3). use real media; unavailable assets -> shapes/text.
+              audio = zero-size Asset; add to tree = play, remove = stop; tracked by node ID + asset key.
+              Use a fresh node to replay a clip (§7.3). Remove old nodes; use bundled media.
               Asset crop (squish-139+): assetInfo.key.{cropLeft,cropTop,cropRight,cropBottom} = % inset per edge -> spritesheets (§7.3.1)
 Button:       no button node + Text isn't clickable -> clickable Shape (onClick) with a Text node on top (§7.2.1)
 

package/export-storage.js

@@ -1,10 +1,10 @@
 'use strict';
 
 // Browser host storage. Embedded in standalone HTML as a self-contained adapter.
-function createExportStorage(window, { installationId, gameId, packageRevision = 'local' }) {
+function createExportStorage(window, { installationId, gameId, packageRevision = 'local', database: sharedDatabase, transaction }) {
     if (typeof installationId !== 'string' || !installationId || typeof gameId !== 'string' || !gameId) throw new Error('Export storage requires a host-selected game identity');
     const key = [installationId, gameId, packageRevision]; let database;
-    const open = () => database ||= new Promise((resolve, reject) => {
+    const open = () => sharedDatabase ? Promise.resolve(sharedDatabase) : database ||= new Promise((resolve, reject) => {
         const request = window.indexedDB.open('homegames-user-exports', 1);
         request.onupgradeneeded = () => request.result.createObjectStore('exports');
         request.onerror = () => reject(request.error);
@@ -35,7 +35,7 @@ function createExportStorage(window, { installationId, gameId, packageRevision =
             validate({ [name]: bytes }); bytes = bytes.slice();
             const db = await open();
             return new Promise((resolve, reject) => {
-                const tx = db.transaction('exports', 'readwrite'), store = tx.objectStore('exports'), request = store.get(key); let error;
+                const tx = transaction ? transaction(['exports']) : db.transaction('exports', 'readwrite'), store = tx.objectStore('exports'), request = store.get(key); let error;
                 request.onsuccess = () => { try { const files = { ...request.result, [name]: bytes }; validate(files); store.put(files, key); } catch (e) { error = e; tx.abort(); } };
                 tx.oncomplete = () => resolve();
                 tx.onabort = () => reject(error || tx.error || new Error('Unable to save export'));

package/game-session.js

@@ -28,17 +28,7 @@ const { squishMap, DEFAULT_SQUISH_VERSION } = require('./game-loader');
 const { MAX_SAVE_DATA_BYTES, SAVE_PUSH_OPCODE, SAVE_REQUEST_OPCODE } = require('./save-games');
 const { normalizeCursor, encodeCursor } = require('./cursor');
 
-// Simple name generator for anonymous players
-const _NAME_WORDS = [
-    'chocolate', 'iguana', 'cardigan', 'enormous', 'gargantuan', 'orangutan',
-    'cookies', 'monstera', 'daisy', 'grapefruit', 'blueberry', 'mango',
-    'elephant', 'bamboo', 'sapphire', 'papaya', 'waffle', 'turquoise',
-    'aquatic', 'goblin', 'funky', 'hotdog', 'elegant', 'cascade', 'euphoria',
-];
-const _generateName = () => {
-    const pick = () => _NAME_WORDS[Math.floor(Math.random() * _NAME_WORDS.length)];
-    return pick() + ' ' + pick();
-};
+const { generateName: _generateName, initialName, normalizeName } = require('./player-identity');
 
 class GameSession {
     constructor(game, squishVersion, opts = {}) {
@@ -161,7 +151,8 @@ class GameSession {
         }
 
         this.players[playerId] = ws;
-        this.playerInfoMap[playerId] = playerOpts.info || {};
+        this.playerInfoMap[playerId] = { ...(playerOpts.info || {}) };
+        const preferredName = playerOpts.playerName === undefined ? null : initialName(playerOpts.playerName);
         this.clientInfoMap[playerId] = playerOpts.clientInfo || {};
         this.playerSettingsMap[playerId] = playerOpts.settings || { SOUND: true };
         if (playerOpts.isRemote) this.remotePlayerMap[playerId] = true;
@@ -183,8 +174,8 @@ class GameSession {
 
                 // Homenames may be unreachable (or have no record yet) — never
                 // hand the game a nameless player.
-                if (!this.playerInfoMap[playerId].name) {
-                    this.playerInfoMap[playerId].name = _generateName();
+                if (preferredName || !this.playerInfoMap[playerId].name) {
+                    this.playerInfoMap[playerId].name = preferredName || _generateName();
                 }
 
                 const playerPayload = {
@@ -244,8 +235,8 @@ class GameSession {
                     .catch(() => finishAdd());
             }
         } else {
-            if (!this.playerInfoMap[playerId].name) {
-                this.playerInfoMap[playerId].name = _generateName();
+            if (preferredName || !this.playerInfoMap[playerId].name) {
+                this.playerInfoMap[playerId].name = preferredName || _generateName();
             }
 
             const playerPayload = {
@@ -384,6 +375,14 @@ class GameSession {
         const pid = Number(playerId);
 
         try {
+            if (input.type === 'player-info') {
+                if (!this.players[playerId]) return;
+                let name; try { name = normalizeName(input.name); } catch (_) { return; }
+                if (this.playerInfoMap[playerId]?.name !== name) this.handlePlayerUpdate(pid, {
+                    info: { ...this.playerInfoMap[playerId], name }, settings: { ...this.playerSettingsMap[playerId] }
+                });
+                return;
+            }
             if (input.type === 'media' && this.players[playerId] && this.media) {
                 if (input.action === 'hello') {
                     this.media.join(pid, { live: false, recording: input.recording === 1 || input.recording === 2, audioRecording: input.recording === 2,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "homegames-common",
-  "version": "1.7.0",
+  "version": "1.7.2",
   "description": "Homegames common tools",
   "main": "index.js",
   "scripts": {

package/player-identity.js

@@ -0,0 +1,31 @@
+'use strict';
+
+// Self-contained: the trusted wrapper also embeds this in downloaded HTML.
+function createPlayerIdentity() {
+    const normalizeName = value => {
+        if (typeof value !== 'string' || /[\u0000-\u001f\u007f-\u009f\u202a-\u202e\u2066-\u2069]/.test(value)) throw new Error('Use a name without control characters.');
+        const name = value.normalize('NFC').trim().replace(/\s+/gu, ' ');
+        if (!name || name.length > 32) throw new Error('Choose a name between 1 and 32 characters.');
+        return name;
+    };
+    const words = ['chocolate', 'iguana', 'cardigan', 'enormous', 'gargantuan', 'orangutan',
+        'cookies', 'monstera', 'daisy', 'grapefruit', 'blueberry', 'mango', 'elephant', 'bamboo',
+        'sapphire', 'papaya', 'waffle', 'turquoise', 'aquatic', 'goblin', 'funky', 'hotdog', 'elegant', 'cascade', 'euphoria'];
+    const generateName = () => Array.from({length: 2}, () => words[Math.floor(Math.random() * words.length)]).join(' ');
+    const initialName = value => { try { return normalizeName(value); } catch (_) { return generateName(); } };
+    function profile(window) {
+        const key = 'homegames-player-name';
+        let name;
+        try { name = normalizeName(window.localStorage.getItem(key)); } catch (_) { name = generateName(); }
+        const set = value => {
+            name = normalizeName(value);
+            // Names still work when storage is disabled or the frame is opaque.
+            try { window.localStorage.setItem(key, name); } catch (_) {}
+            return name;
+        };
+        set(name);
+        return { get: () => name, set };
+    }
+    return { normalizeName, generateName, initialName, profile };
+}
+module.exports = { createPlayerIdentity, ...createPlayerIdentity() };

package/player-toolbar.js

@@ -3,7 +3,7 @@
 // Client UI only. Self-contained so the same toolbar can be embedded in a
 // downloaded HTML without loading scripts or styles from a website.
 function createPlayerToolbar(window, options = {}) {
-    const document = window.document, actions = new Map();
+    const document = window.document, actions = new Map(), running = new Set();
     const element = (tag, className, text) => {
         const node = document.createElement(tag); node.className = className;
         if (text) node.textContent = text; return node;
@@ -15,67 +15,117 @@ function createPlayerToolbar(window, options = {}) {
 .hg-player-bar *,.hg-player-menu *{box-sizing:border-box}
 .hg-player-bar{display:flex;flex:none;align-items:center;gap:6px;width:100%;height:calc(58px + env(safe-area-inset-top));padding:calc(6px + env(safe-area-inset-top)) max(10px,env(safe-area-inset-right)) 6px max(10px,env(safe-area-inset-left));border-bottom:1px solid #363b36}
 .hg-player-heading{flex:1;min-width:0}.hg-player-title{margin:0;font-size:14px;font-weight:600;white-space:nowrap;overflow:hidden;text-overflow:ellipsis}
+.hg-player-identity{display:flex;align-items:baseline;gap:10px;min-width:0}.hg-player-author{font-size:12px;font-weight:400;color:#b7bfb5;margin-left:6px}
 .hg-player-status{margin:0;color:#b7bfb5;font-size:11px;white-space:nowrap;overflow:hidden;text-overflow:ellipsis}
 .hg-player-bar button,.hg-player-bar a,.hg-player-menu button{font:inherit;color:inherit;border:1px solid #4a5049;border-radius:8px;background:transparent;cursor:pointer;text-decoration:none}
 .hg-player-bar button,.hg-player-bar a{display:inline-flex;align-items:center;justify-content:center;flex:none;min-width:40px;height:44px;padding:0 10px;white-space:nowrap}
 .hg-player-bar .hg-player-icon{font-size:21px;padding:0;width:40px}
+.hg-player-home img{display:block;width:32px;height:32px;object-fit:contain}
+.hg-player-bar .hg-player-brand{height:auto;min-height:24px;min-width:0;padding:0;border:0;border-radius:3px;color:#94d2e5;font-size:12px;text-decoration:underline;text-underline-offset:3px}
+.hg-player-bar .hg-player-brand:hover{background:transparent;color:#b9e5f1}
 .hg-player-bar .hg-player-share{background:#fff78e;color:#22261e;border-color:#fff78e;font-weight:600}
 .hg-player-bar button:hover,.hg-player-bar a:hover,.hg-player-menu button:hover{background:#394036}
 .hg-player-bar .hg-player-share:hover{background:#fffbb5}
+.hg-player-bar .hg-player-install{background:#a8edc9;color:#17271e;border-color:#a8edc9;font-weight:600}.hg-player-bar .hg-player-install:hover{background:#c4f5dc}
 .hg-player-bar :focus-visible,.hg-player-menu :focus-visible{outline:2px solid #fff78e;outline-offset:2px}
 .hg-player-bar [hidden],.hg-player-menu [hidden]{display:none!important}
 .hg-player-bar button:disabled,.hg-player-menu button:disabled{opacity:.45;cursor:default}
-.hg-player-bar.hg-player-simple .hg-player-status{position:absolute;width:1px;height:1px;overflow:hidden;clip-path:inset(50%)}
+.hg-player-edit-short{display:none}
+@media(max-width:600px){.hg-player-edit-long{display:none}.hg-player-edit-short{display:inline}.hg-player-bar{gap:4px;flex-wrap:wrap;height:auto}.hg-player-home{order:-2}.hg-player-heading{order:-1;flex-basis:calc(100% - 48px)}.hg-player-share{margin-left:auto}.hg-player-bar button:not(.hg-player-icon){padding:0 8px}}
 .hg-player-menu{position:fixed;inset:max(68px,env(safe-area-inset-top)) 12px auto auto;margin:0;width:min(320px,calc(100vw - 24px));max-height:calc(100dvh - 90px);overflow:auto;padding:16px;border:1px solid #4a5049;border-radius:12px;box-shadow:0 16px 50px #0008}
 .hg-player-menu::backdrop{background:#080c0a99}.hg-player-menu h2{margin:0 0 12px;font-size:16px}
 .hg-player-menu-actions{display:flex;flex-direction:column;gap:6px}.hg-player-menu button{width:100%;min-height:44px;padding:10px 12px;text-align:left}
 .hg-player-menu .hg-player-menu-status{font-size:12px;color:#b7bfb5;overflow-wrap:anywhere;margin:12px 0}
 .hg-player-menu .hg-player-menu-close{text-align:center;margin-top:10px}
+.hg-player-name{margin:0 0 16px;padding-bottom:16px;border-bottom:1px solid #4a5049}
+.hg-player-name label{display:block;margin-bottom:6px}.hg-player-name input{width:100%;min-height:44px;padding:10px;font:inherit;color:inherit;background:#141815;border:1px solid #4a5049;border-radius:8px}
+.hg-player-name button{margin-top:8px}.hg-player-name p{font-size:12px;color:#b7bfb5;margin:8px 0 0;overflow-wrap:anywhere}
 `;
     bar.append(style);
-    const home = element(typeof options.home === 'string' ? 'a' : 'button', 'hg-player-icon', '⌂');
+    const home = element(typeof options.home === 'string' ? 'a' : 'button', 'hg-player-icon hg-player-home');
     home.setAttribute('aria-label', 'Home'); home.title = 'Home'; home.hidden = !options.home;
+    // Embedded copy of homegamesio/favicon-32x32.png; no network request in downloaded games.
+    const logo = element('img', ''); logo.alt = ''; logo.width = logo.height = 32;
+    logo.src = 'data:image/png;base64,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'; home.append(logo);
     if (typeof options.home === 'string') home.href = options.home;
     else { home.type = 'button'; home.onclick = options.home; }
     const heading = element('div', 'hg-player-heading');
-    const title = element('h1', 'hg-player-title'), status = element('p', 'hg-player-status');
-    status.setAttribute('role', 'status'); status.setAttribute('aria-atomic', 'true'); heading.append(title, status);
-    const exportsButton = element('button', 'hg-player-icon', '⇩');
-    exportsButton.type = 'button'; exportsButton.title = 'View exports'; exportsButton.setAttribute('aria-label', 'View exports'); exportsButton.hidden = true;
+    const identity = element('div', 'hg-player-identity'), title = element('h1', 'hg-player-title'), titleName = element('span', ''), author = element('span', 'hg-player-author'), status = element('p', 'hg-player-status');
+    title.append(titleName, author);
+    const website = element('a', 'hg-player-brand', 'homegames.io');
+    website.href = 'https://homegames.io/'; website.target = '_blank'; website.rel = 'noopener noreferrer'; website.title = 'Open homegames.io in a new tab';
+    identity.append(title, website);
+    status.setAttribute('role', 'status'); status.setAttribute('aria-atomic', 'true'); heading.append(identity, status);
     const share = element('button', 'hg-player-share', 'Share'); share.type = 'button'; share.hidden = true;
     const more = element('button', 'hg-player-icon', '⋯'); more.type = 'button'; more.title = 'More';
     more.setAttribute('aria-label', 'More'); more.setAttribute('aria-haspopup', 'dialog');
-    const downloadButton = element('button', '', 'Download'); downloadButton.type = 'button'; downloadButton.hidden = true;
-    if (options.simple) { bar.classList.add('hg-player-simple'); more.hidden = true; }
-    bar.append(home, heading, exportsButton, share, downloadButton, more);
+    const downloadButton = element('button', '', 'Download file'); downloadButton.type = 'button'; downloadButton.hidden = true;
+    const installButton = element('button', 'hg-player-install', 'Download app'); installButton.type = 'button'; installButton.hidden = true;
+    const editButton = element('button', 'hg-player-edit'); editButton.type = 'button'; editButton.hidden = true;
+    editButton.title = 'Open your own editable copy in Studio'; editButton.setAttribute('aria-label', 'Edit this game');
+    editButton.append(element('span', 'hg-player-edit-long', 'Edit this game'), element('span', 'hg-player-edit-short', 'Edit'));
+    const primary = new Set([share, installButton, downloadButton, editButton]);
+    bar.append(home, heading, share, installButton, downloadButton, editButton, more);
     const menu = element('dialog', 'hg-player-menu'); menu.setAttribute('aria-label', 'Game options');
     const menuTitle = element('h2', '', 'Game options'), list = element('div', 'hg-player-menu-actions');
+    const placeDownload = () => {
+        // Installable players get one primary download action; their portable
+        // file remains available in More. File-only players keep it in the bar.
+        if (actions.has('install') && !installButton.hidden) { list.prepend(downloadButton); downloadButton.textContent = 'Download game file (HTML)'; }
+        else { bar.insertBefore(downloadButton, editButton); downloadButton.textContent = 'Download file'; }
+    };
     const menuStatus = element('p', 'hg-player-menu-status');
+    const nameForm = element('form', 'hg-player-name'); nameForm.hidden = true;
+    const nameLabel = element('label', '', 'Your name'), nameInput = element('input', '');
+    nameInput.type = 'text'; nameInput.maxLength = 32; nameInput.required = true; nameInput.autocomplete = 'nickname';
+    nameInput.setAttribute('aria-label', 'Your name'); nameLabel.append(nameInput);
+    const nameSave = element('button', '', 'Save name'); nameSave.type = 'submit';
+    const nameStatus = element('p', ''); nameStatus.setAttribute('role', 'status');
+    nameForm.append(nameLabel, nameSave, nameStatus);
+    let playerName = '', changeName;
+    nameForm.onsubmit = async event => {
+        event.preventDefault(); if (!changeName || nameSave.disabled) return;
+        nameSave.disabled = true;
+        try { playerName = await changeName(nameInput.value); nameInput.value = playerName; nameStatus.textContent = 'Name updated for this session.'; }
+        catch (error) { nameStatus.textContent = error.message || String(error); }
+        finally { nameSave.disabled = false; }
+    };
     const done = element('button', 'hg-player-menu-close', 'Done'); done.type = 'button'; done.onclick = () => menu.close();
-    menu.append(menuTitle, list, menuStatus, done); document.body.append(menu);
+    menu.append(menuTitle, nameForm, list, menuStatus, done); document.body.append(menu);
     let menuActive = false;
     const resume = () => { if (menuActive) { menuActive = false; options.onClose?.(); } };
-    more.onclick = () => { if (!menu.open) { menuActive = true; options.onOpen?.(); menu.showModal(); } };
+    more.onclick = () => { if (!menu.open) { nameInput.value = playerName; nameStatus.textContent = ''; menuActive = true; options.onOpen?.(); menu.showModal(); } };
     menu.addEventListener('close', resume);
     menu.addEventListener('click', event => { if (event.target === menu) { const r = menu.getBoundingClientRect(); if (event.clientX < r.left || event.clientX > r.right || event.clientY < r.top || event.clientY > r.bottom) menu.close(); } });
     let disposed = false;
     const api = {
         bar, menu, statusElement: status,
-        setTitle(value) { title.textContent = title.title = value || 'Homegames'; },
+        setTitle(value) { titleName.textContent = titleName.title = value || 'Homegames'; },
+        setAuthor(value) { author.textContent = typeof value === 'string' && value.trim() ? ' by ' + value.trim().slice(0, 200) : ''; author.title = author.textContent.trim(); author.hidden = !author.textContent; },
         setStatus(value) { status.textContent = status.title = menuStatus.textContent = value || ''; },
+        setPlayerName(value, onChange) {
+            playerName = value; changeName = onChange; nameForm.hidden = !onChange;
+            if (!menu.open) nameInput.value = value;
+            if (onChange) more.hidden = false;
+        },
         setAction(key, value) {
-            if (!value) { const old = actions.get(key); if (old) { old.hidden = true; if (old !== share && old !== exportsButton && old !== downloadButton) old.remove(); actions.delete(key); } return; }
+            if (!value) { const old = actions.get(key); if (old) { old.hidden = true; if (!primary.has(old)) old.remove(); actions.delete(key); } if (key === 'install') placeDownload(); return; }
             let button = actions.get(key);
-            if (!button) { button = key === 'share' ? share : key === 'exports' ? exportsButton
-                : options.simple && key === 'download-html' ? downloadButton : element('button', '', value.label);
-                button.type = 'button'; actions.set(key, button); if (button !== share && button !== exportsButton && button !== downloadButton) list.append(button); }
+            if (!button) { button = key === 'share' ? share : key === 'edit-game' ? editButton
+                : key === 'install' ? installButton : key === 'download-html' ? downloadButton : element('button', '', value.label);
+                button.type = 'button'; actions.set(key, button); if (!primary.has(button)) list.append(button); }
             if (value.id) button.id = value.id;
-            if (button !== exportsButton) button.textContent = button === downloadButton ? 'Download' : value.label;
-            button.hidden = !!value.hidden || (options.simple && button === exportsButton); button.disabled = !!value.disabled;
+            if (button !== editButton) button.textContent = value.label;
+            button.hidden = !!value.hidden; button.disabled = !!value.disabled || running.has(key);
+            if (key === 'install' || key === 'download-html') placeDownload();
             button.onclick = () => {
+                if (running.has(key)) return;
                 if (menu.open) { menu.close(); resume(); }
-                try { Promise.resolve(value.run()).catch(error => api.setStatus(error.message || String(error))); }
-                catch (error) { api.setStatus(error.message || String(error)); }
+                running.add(key); button.disabled = true;
+                // Invoke synchronously: opening Studio needs the click gesture.
+                try { Promise.resolve(value.run()).catch(error => api.setStatus(error.message || String(error)))
+                    .finally(() => { running.delete(key); button.disabled = !!value.disabled; }); }
+                catch (error) { running.delete(key); button.disabled = !!value.disabled; api.setStatus(error.message || String(error)); }
             };
             options.onActionReady?.(key);
         },
@@ -84,7 +134,7 @@ function createPlayerToolbar(window, options = {}) {
         dispose() { if (disposed) return; disposed = true; if (menu.open) menu.close(); menu.remove(); bar.remove(); },
     };
     bar.homegamesToolbar = api;
-    api.setTitle(options.title); api.setStatus(options.status);
+    api.setTitle(options.title); api.setAuthor(options.author); api.setStatus(options.status);
     for (const [key, value] of Object.entries(options.actions || {})) api.setAction(key, value);
     return api;
 }

package/portable-client.js

@@ -4,6 +4,7 @@
 function attachClientHost(window, frame, recordAudio, exportStorage, createExportsViewer, recordVideo, createPlayerToolbar, options = {}) {
     const document = window.document;
     let port, sequence = 0, closed = false, toolbar = options.toolbar, ownToolbar = false, recording, viewer;
+    let gameTitle = options.title;
     const pending = new Map();
     function request(format, name) {
         if (!port || closed) return Promise.reject(new Error('The player is not ready'));
@@ -13,12 +14,18 @@ function attachClientHost(window, frame, recordAudio, exportStorage, createExpor
         });
     }
     const status = text => { if (options.onPlayerStatus) options.onPlayerStatus(text); else toolbar?.setStatus(text); };
-    function command(action) { if (port && !closed) port.postMessage({ type: 'player-control', action }); }
+    function command(action, value) { if (port && !closed) port.postMessage({ type: 'player-control', action, value }); }
     async function download(format) {
         try {
+            // The host can supply a recovered catalog name for older packs.
+            // Otherwise use the title announced by the current game. Keep this
+            // self-contained: this adapter is also embedded in downloaded HTML.
+            const name = typeof options.downloadName === 'function' ? options.downloadName() : options.downloadName;
+            let stem = String(name || gameTitle || 'game').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 80) || 'game';
+            if (/^(con|prn|aux|nul|com[1-9]|lpt[1-9])$/.test(stem)) stem += '-game';
             status('Preparing game download…');
             const bytes = await request(format), url = window.URL.createObjectURL(new Blob([bytes], { type: format === 'html' ? 'text/html' : 'application/zip' }));
-            const link = document.createElement('a'); link.href = url; link.download = 'my-game.' + format; link.click();
+            const link = document.createElement('a'); link.href = url; link.download = stem + '.' + format; link.click();
             setTimeout(() => window.URL.revokeObjectURL(url), 30000); status('Game copy downloaded');
         } catch (e) { status(e.message); }
     }
@@ -28,14 +35,21 @@ function attachClientHost(window, frame, recordAudio, exportStorage, createExpor
         port.onmessage = event => {
             const message = event.data;
             if (!closed && message?.type === 'player-state') {
-                if (typeof message.title === 'string') toolbar?.setTitle(message.title.slice(0, 200));
+                if (typeof message.title === 'string') { gameTitle = message.title.slice(0, 200); toolbar?.setTitle(gameTitle); }
+                if (typeof message.author === 'string') toolbar?.setAuthor?.(message.author.slice(0, 200));
                 if (typeof message.status === 'string') status(message.status.slice(0, 300));
                 if (message.ready) {
+                    toolbar?.setPlayerName(options.profile?.get() || '', message.playerNames && options.profile ? value => {
+                        if (closed) throw new Error('This player has closed. Reopen the game to change your name.');
+                        const name = options.profile.set(value); command('player-name', name); return name;
+                    } : null);
                     for (const [key, label] of [['share', 'Share'], ['copy-share', 'Share a copy'], ['manual-connect', 'Manual connection'], ['exports', 'View exports']]) {
                         toolbar?.setAction(key, key !== 'exports' && !message.sharing ? null : { label, run: () => command(key) });
                     }
                     toolbar?.setAction('download-html', { label: 'Download game HTML', id: options.htmlId, run: () => download('html') });
                     toolbar?.setAction('download-zip', { label: 'Download game ZIP', id: options.zipId, run: () => download('zip') });
+                    if (options.editGame) toolbar?.setAction('edit-game', { label: 'Edit this game', id: 'edit-game',
+                        run: () => options.editGame(() => request('zip')) });
                 }
                 return;
             }
@@ -71,9 +85,9 @@ function attachClientHost(window, frame, recordAudio, exportStorage, createExpor
             else if (!(message.bytes instanceof Uint8Array) || !message.bytes.length || message.bytes.length > (entry.format === 'html' ? 220 : 65) * 1024 * 1024) entry.reject(new Error('Invalid game download'));
             else entry.resolve(message.bytes);
         };
-        frame.contentWindow.postMessage({ type: 'homegames-client-port-v1' }, '*', [channel.port2]);
+        frame.contentWindow.postMessage({ type: 'homegames-client-port-v1', playerName: options.profile?.get() }, '*', [channel.port2]);
         if (!toolbar && createPlayerToolbar) {
-            toolbar = createPlayerToolbar(window, { title: options.title, home: options.home, status: 'Starting game…',
+            toolbar = createPlayerToolbar(window, { title: options.title, author: options.author, home: options.home, status: 'Starting game…',
                 onOpen: () => command('pause-input'), onClose: () => command('resume-input') });
             ownToolbar = true; frame.before(toolbar.bar);
         }
@@ -85,18 +99,21 @@ function attachClientHost(window, frame, recordAudio, exportStorage, createExpor
         for (const entry of pending.values()) { clearTimeout(entry.timer); entry.reject(new Error('Player closed')); } pending.clear(); } };
 }
 function connectClientSource(window, download, exports = {}, controls = {}) {
-    let port, closed = false, sequence = 0, resolveConnect, state;
+    let port, closed = false, sequence = 0, resolveConnect, state, playerName;
     const recordings = new Map();
     const connected = new Promise(resolve => { resolveConnect = resolve; });
     const connectTimer = setTimeout(resolveConnect, 15000);
     const listener = event => {
         if (closed || event.source !== window.parent || event.data?.type !== 'homegames-client-port-v1' || !event.ports[0]) return;
-        window.removeEventListener('message', listener); port = event.ports[0]; clearTimeout(connectTimer); resolveConnect();
+        window.removeEventListener('message', listener); port = event.ports[0]; playerName = event.data.playerName; clearTimeout(connectTimer); resolveConnect();
         if (state) port.postMessage({ type: 'player-state', ...state });
         port.onmessage = async event => {
             const message = event.data;
             if (!closed && message?.type === 'player-control' && Object.hasOwn(controls, message.action)) {
-                try { await controls[message.action](); } catch (error) { port.postMessage({type:'player-state', status:error.message}); }
+                try {
+                    if (message.action === 'player-name') playerName = message.value;
+                    await controls[message.action](message.value);
+                } catch (error) { port.postMessage({type:'player-state', status:error.message}); }
                 return;
             }
             if (message?.type === 'audio-result' || message?.type === 'export-result') { const entry = recordings.get(message.id); if (!entry) return; recordings.delete(message.id); clearTimeout(entry.timer); message.error ? entry.reject(new Error(message.error)) : entry.resolve(message.value); return; }
@@ -127,6 +144,7 @@ function connectClientSource(window, download, exports = {}, controls = {}) {
         });
     });
     return { setState(value) { state = { ...state, ...value }; if (!closed) port?.postMessage({ type:'player-state', ...state }); },
+        getPlayerName: async () => { await connected; return playerName; },
         recordAudio: info => request('record-audio', {recording:info}),
         recordVideo: info => request('record-video', {recording:info}),
         viewExports: () => request('view-exports'),