homegames-common 1.7.1 → 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
@@ -939,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`+)
 
@@ -1987,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.
@@ -2025,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/package.json

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

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,17 +15,23 @@ 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}
@@ -36,23 +42,38 @@ function createPlayerToolbar(window, options = {}) {
 .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,iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAYAAABzenr0AAAIbElEQVRYR7WXC1BU5xmGn7M3rgICYRHjBQSiBUIUTQQ0oEZTIRdTihcy04xO22mbSWKTTDQql2jNbdKk06S2TdqmaWrspMk0tHViiEpqEEyCGmhEq0gEXS4r7HJZll2WPX/nnLO7LEhsOp3+Mwxw9j//9/7v973v9620cOHCpKSkab9blJ2wSq/XGfh/LwFjsjx2usl6pLt7eLNUXHz7oTde/eadcbFhWmgBQgIJgUBC+h8BKacop00+p882wgPfPfSBVL7j257d5fkGbdv4EsL/qvbc/7ny++ssBTyyjKSTkKSpr1Gx57hHqiovFZU7V4EY8Z2rhdrwncMMDnlU7BPeVz+eDNdHne8KQoAsBCGhISSazdya7GTL1iWBC/rfrnq6HqmqfIOo3HUXyL2BFKCDbRXtHDt2gp6eHvUWCgVRRiODHo9GiSwIIAtiy/9MYVB5J2dxDsuT3Dy8twAM+gnk+QBsFJW77gbZOs6AJLH3BTvV1e9jsVjUgMqlf7W+kG3V9USajLy+ppDdJ0+xaFossyIjOdLdyS1JZowmwe6PTvpyJpGVmcnam0w8sud2MAXVuIDKZwIMKACuTgCwvaKdo7XHsXRatMIE9m8p5u0Pm1m5dC4mg57pYdEkRZuYPiDhjoYuvZ5+ay8PvFmDEFruMzMzKUo38dDeAiTjJAb2qgDWi8qd6xCiFwmvBkKCR7e3Unf8U40B5ZEkcfgHmxh1OegQLvqdHgpnmOmQBPMU9U4LZ8zl5d32L3j+T59qRStJ5Ofnk2t2snVvIUwGEKiB8m+B3AfCPQWAzgAzBx7cxO9rT3JHlpmspFTkkV4coZGkm4wMhoXy5fmLtPQN81zNiQDodevWMU9q58dPXw9ARSl4e8eVIMHWJ85T39AYYEA58b6FqbT09HJf3gJiB3X8yzRIavh02vtspMyMp/3MVdLzZvHIy4cCAMrKykh0tvDosyvAoAuIXRH5U083+FRQvkFTgRj2MSAovf8j2ju6AgDmL78DecyN5exZbi3ZQP3+18guXo+to5VLTadYtmkzXxyuJnPlvTTX/AVbj1VNgQLA7GzhsWdXIAx6TYo+HY7LsLxMCy73+KQouGd9Dd09fQEA237+E/qGvDSfOM3tKzKw2Vyk3LYMEZqArbmWcJMbXUQiMfE30FhTzYFX3lIVWVRURLrRwuPPrQySoWZnVeMM3A+yHYTN58aCH25t4dSppoAKVtxTTEFpCQdf+xlL79tE5k3zuNjayoz5GcToZa5YrZyr/RsRC4o4+FIllo6rKgNZWVmsSJZ44vlV1/hA5bgRlYKwBopQMZEdu7s5cuQoFkuXylnmslzyVq0m/Rtx1LxXy90bS+jquEzs/ExMDhtNdR9yutmKY2CYgrtW8VrFHhVARkYGBXP17PipBiDYQ30ANoqKnfciie5AcpQCeWzHJerq6rFYFBVI3PXQI+TnzuPsyVZuSE2lp7mO6NlpzLoplQt1h4nLXov70se445aQEnqZbd+rUoNlZWZRmKxju8LA1DJUnPCe8fz7klC2pZ6LFzvo6uxSfcFo1GFOiKCr28HcOTFcbLMTHx/OwIALvV5iekwo1t5hEm6IYNTt5WqvE51OR3Z2NoVzBI8pVhxi/CorngwASspqcDjGUD19ihWg0t8qfQam9nL17lqrSElOITO8iwefKmDEK2g+04t9SPF2He++06TIcFIv8J3c39iBo92O1yuPN2qdRN+QB48smBFtCjQvrXH7BeT/2wdEQHiogVr9bM5dTSI5bzV2lwe3vZeGd94cByBk64S+779F8OWVoxtOdJG3dMaUrEz10OsVvHjATbc8l9mLcjGGhuAntfbXLwa1Y8UJ/Wvy/OBj5czZPszmcOJ901PwXScH96fo8HE7ZxzL0CdnBAYTJTXKvFDzygu+ZrSrGGQbQ0OjnD9uBYNEzh1J14xkxxs6yc9N+tq3VzbuPxLDYEI+clikSqrX6cAQEYnD5eHYqy8pAJSJqAhEP22XBhj8bT8WSaZ499wJALyyzJkWGzdnxk0e3ib9r+Hr7RuhqcXBwaY4ZubfTWhkJMLj4kLDx8y8eTF2YeKff/yFH8BKhHDR0T5I2x/aabMNsOWlZRNmxI4rQ0RNCyHGX3xBnj6ZEoXJl2tuxDw3A5cxgguN9aQtX62qYqTfjtMQxpBrjJa39iFV7VIYyFPP8Hi8nG/t59x5GyX3pgWahpLPzxq7uXVx4qRYU82GcPQfl3mvczlExasF57S0kbHkNgwR0+hzuHF6xtTLqQB2bC8Rjz+8GJ1Oi6f8DDs8NJ62snhhAgajnk8/62bBgjgiwrWRSis+4avmoLFb0sbvY5/YsaQ8RPfwqDrKDVst6OUxwhLnqDYhZBnvqItzb/8G6dE1a8T3k5PVU9Vu7RuBlWPtzmGcHg8zY2PBaFDNwy9+oexTNikDq06nTs+qaY2OcmJ4BPuDFVgGXGpA2TNKV937xMxOQa/TodfriYoMp/nv7yDtLCoST6T56A64mS+OP4bJhBQZca01KCAUAJJOBS68MmLUTd2VK3yy+UmcsqZnr2cU0dbMjWnzYagfp1fGiJcTf/1zEIDrimvqXOuio8HpRFZG9aD1pWOIN1aXYTDPVp86Oi8h6fREJM6asO/sgV9OBHBtmKkDX98IBF4BVRHxuNJziJqTykD1G0TeWYo+LEJ9VTNpQcv+fUjb1671PJmWbvDPSl/3+6CS70C9BH1H8YPrGxjg4zFlBNCTO2Sn1RCCNSwcvceDwe0mZHSEalufR1qbl3do3y233BlrnNgq/5Pd/XfcjO/WvtkJbGNj/Ojzzz+QcnJyZiSEhLyeHRW1UidJX4kiuOteD5yfXlUVX7FRFsLTNDh41Op2b/43wV/aTZKTkWoAAAAASUVORK5CYII='; 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', '');
@@ -79,7 +100,8 @@ function createPlayerToolbar(window, options = {}) {
     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;
@@ -87,18 +109,23 @@ function createPlayerToolbar(window, options = {}) {
             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);
         },
@@ -107,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'));
@@ -16,9 +17,15 @@ function attachClientHost(window, frame, recordAudio, exportStorage, createExpor
     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,7 +35,8 @@ 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 => {
@@ -40,6 +48,8 @@ function attachClientHost(window, frame, recordAudio, exportStorage, createExpor
                     }
                     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;
             }
@@ -77,7 +87,7 @@ function attachClientHost(window, frame, recordAudio, exportStorage, createExpor
         };
         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);
         }

package/portable-html.js

@@ -10,6 +10,7 @@ const { recordVideo } = require('./video-recording');
 const { createExportStorage } = require('./export-storage');
 const { createPlayerToolbar } = require('./player-toolbar');
 const { createPlayerIdentity } = require('./player-identity');
+const { openGameInStudio } = require('./studio-handoff');
 const inline = value => JSON.stringify(value).replace(/</g, '\\u003c');
 const escapeHtml = value => String(value).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
 const filename = name => {
@@ -39,7 +40,7 @@ function base64(bytes) {
     return btoa(binary);
 }
 
-async function runtimeDocument(project, { clientBundleSource, installationId, sharing = {} } = {}) {
+async function runtimeDocument(project, { clientBundleSource, installationId, sharing = {}, studioUrl, studioDebug = false } = {}) {
     if (!clientBundleSource?.includes('PortableProject')) throw new Error('Rebuild the Homegames client before playing portable projects');
     if (!/^[a-zA-Z0-9-]{16,80}$/.test(installationId || '')) throw new Error('Missing local installation ID');
     const signal = new URL(sharing.signalingUrl || 'wss://api.homegames.io/rtc');
@@ -47,9 +48,11 @@ async function runtimeDocument(project, { clientBundleSource, installationId, sh
     signal.protocol = signal.protocol === 'https:' ? 'wss:' : signal.protocol === 'http:' ? 'ws:' : signal.protocol;
     const join = new URL(sharing.joinUrl || 'https://homegames.io/play.html');
     if (!['http:', 'https:'].includes(join.protocol)) throw new Error('Invalid invitation URL');
+    const studio = new URL(studioUrl || '/studio.html', join);
+    if (!['http:', 'https:'].includes(studio.protocol) || studio.username || studio.password) throw new Error('Invalid Studio URL');
     const receive = new URL(sharing.receiveUrl || '/game-app.html', join);
     if (!['http:', 'https:'].includes(receive.protocol)) throw new Error('Invalid copy receiver URL');
-    const payload = { archive: base64(await exportArchive(project)), installationId,
+    const payload = { archive: base64(await exportArchive(project)), installationId, studioUrl: studio.href, studioDebug: studioDebug === true,
         sharing: sharing === false ? false : { signalingUrl: signal.href, joinUrl: join.href, receiveUrl: receive.href } };
     // No cookies, storage, parent DOM, navigation, popup or download permission.
     // Network access is limited by CSP to the signaling endpoint; RTC itself is
@@ -61,7 +64,7 @@ html,body{margin:0;height:100%;background:#101820;color:#f7fafc;font:14px system
 <script>${clientBundleSource.replace(/<\/script/gi, '<\\/script')}</script><script>
 (async()=>{
 const payload=${inline(payload)};
-let client,clientSource,copyShare,pairing;
+let client,clientSource,copyShare,pairing,debug;
 const state=status=>clientSource?.setState({status});
 const fail=error=>{document.getElementById('error').hidden=false;document.getElementById('error').textContent=error.message||String(error);state('Unable to play: '+(error.message||String(error)));};
 try {
@@ -72,19 +75,20 @@ const shareCopy=async()=>{const copy=await client.requestGameCopy();copyShare?.c
 clientSource=HomegamesClient.PortableProject.connectClientSource(window,async format=>{
 const copy=await client.requestGameCopy();
 if(format==='zip')return copy.bytes;
-return new TextEncoder().encode(await HomegamesClient.PortableProject.buildIsolatedHtml(copy.project,{clientBundleSource:document.scripts[0].textContent,installationId:crypto.randomUUID(),sharing:payload.sharing}));
+return new TextEncoder().encode(await HomegamesClient.PortableProject.buildIsolatedHtml(copy.project,{clientBundleSource:document.scripts[0].textContent,installationId:crypto.randomUUID(),sharing:payload.sharing,studioUrl:payload.studioUrl}));
 },{list:()=>client.listExports(),read:name=>client.readExport(name)}, {
 share:()=>client.showShare(),exports:()=>client.viewExports(),'copy-share':shareCopy,'manual-connect':()=>pairing?.show(),
-'pause-input':()=>client.setInputEnabled(false),'resume-input':()=>client.setInputEnabled(true),'player-name':name=>client.setPlayerName(name)
+'pause-input':()=>client.setInputEnabled(false),'resume-input':()=>{client.setInputEnabled(true);if(payload.studioDebug)client._localSession?._updateInputAttachment();},'player-name':name=>client.setPlayerName(name)
 });
-const ready=status=>clientSource.setState({title:project.metadata.name||'Homegame',status,ready:true,sharing:!!payload.sharing,playerNames:typeof client.setPlayerName==='function'});
+const ready=status=>clientSource.setState({title:project.metadata.name||'Homegame',author:project.metadata.author||project.metadata.createdBy||'',status,ready:true,sharing:!!payload.sharing,playerNames:typeof client.setPlayerName==='function'});
 client=new HomegamesClient({containerId:'game',chrome:false,localHome:false,share:payload.sharing,saveStore,platform:clientSource,playerName:await clientSource.getPlayerName?.(),
 loadLocalGame:async()=>HomegamesClient.PortableProject.prepareTrustedLocalGame(project,{trusted:true,installationId:payload.installationId}),
-onReady:()=>ready('Playing locally'),onSessionStatus:state,onError:fail});
+onReady:()=>{ready('Playing locally');debug?.ready();},onSessionStatus:state,onError:fail});
 pairing=payload.sharing?HomegamesClient.createManualPairing({container:document.body,getSession:()=>client._localSession,
 onOpen:()=>client.setInputEnabled(false),onClose:()=>client.setInputEnabled(true),
-join:async transport=>{client.stop();client=new HomegamesClient({containerId:'game',chrome:false,transport,platform:clientSource,playerName:await clientSource.getPlayerName?.(),onReady:()=>ready('Connected manually to host'),onClose:()=>state('Host disconnected'),onError:fail});client.start();}}):null;
-window.addEventListener('pagehide',()=>{copyShare?.close();pairing?.dispose();client.stop();clientSource.close();});client.startLocalGame({});
+join:async transport=>{client.stop();client=new HomegamesClient({containerId:'game',chrome:false,transport,platform:clientSource,playerName:await clientSource.getPlayerName?.(),onReady:()=>{ready('Connected manually to host');debug?.ready();},onClose:()=>state('Host disconnected'),onError:fail});client.start();}}):null;
+if(payload.studioDebug)debug=HomegamesClient.PortableProject.connectStudioDebugSource(window,()=>client._localSession);
+window.addEventListener('pagehide',()=>{debug?.close();copyShare?.close();pairing?.dispose();client.stop();clientSource.close();});client.startLocalGame({});
 }catch(error){fail(error);}
 })();
 </script></body></html>`;
@@ -93,11 +97,12 @@ window.addEventListener('pagehide',()=>{copyShare?.close();pairing?.dispose();cl
 function createFrame(document, source) {
     const frame = document.createElement('iframe');
     frame.title = 'Game preview';
-    // frame.setAttribute('sandbox', 'allow-scripts');
     // Pointer Lock still requires a canvas gesture. Keep the opaque origin:
     // enabling mouse capture does not grant parent/storage access.
     frame.setAttribute('sandbox', 'allow-scripts allow-pointer-lock');
-    frame.setAttribute('allow', "autoplay *; fullscreen *; camera 'none'; microphone 'none'; geolocation 'none'");
+    // Explicit delegation also covers browsers that restrict gamepads in
+    // cross-origin frames. '*' is needed for this frame's opaque origin.
+    frame.setAttribute('allow', "autoplay *; fullscreen *; gamepad *; camera 'none'; microphone 'none'; geolocation 'none'");
     frame.referrerPolicy = 'no-referrer';
     frame.srcdoc = source;
     return frame;
@@ -105,7 +110,9 @@ function createFrame(document, source) {
 
 async function buildIsolatedHtml(project, options) {
     const document = await runtimeDocument(project, options);
-    const payload = inline({ formatVersion: 1, document, archive: base64(await exportArchive(project)), name: filename(project.metadata.name), title:project.metadata.name||'Homegame',
+    const studioUrl = new URL(options.studioUrl || '/studio.html', options.sharing?.joinUrl || 'https://homegames.io/play.html').href;
+    const payload = inline({ formatVersion: 1, document, archive: base64(await exportArchive(project)), name: filename(project.metadata.name), title:project.metadata.name||'Homegame', author:project.metadata.author||project.metadata.createdBy||'',
+        studioUrl, homeUrl: new URL('/catalog.html', studioUrl).href,
         saves:{packageRevision:project.revision,installationId:options.installationId,gameId:project.manifest.gameId,versionId:'save-schema:'+project.manifest.saveSchemaVersion,compatibility:project.metadata.saveCompatibility || []} });
     return `<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1,viewport-fit=cover"><title>${escapeHtml(project.metadata.name || 'Homegame')}</title>
 <style>html,body{margin:0;height:100%;background:#101820;color:#f7fafc;font:14px system-ui}body{display:flex;flex-direction:column}iframe{flex:1;width:100%;border:0;min-height:0}[hidden]{display:none!important}</style></head><body>
@@ -114,12 +121,14 @@ async function buildIsolatedHtml(project, options) {
 <script>const payload=JSON.parse(document.getElementById('homegames-project').textContent);
 const originalHtml='<!doctype html>\\n'+document.documentElement.outerHTML;
 let frame,saveHost,clientHost;
-const toolbar=(${createPlayerToolbar.toString()})(window,{title:payload.title,status:'Starting game…',onOpen:()=>clientHost?.command('pause-input'),onClose:()=>clientHost?.command('resume-input')});document.body.prepend(toolbar.bar);
+const toolbar=(${createPlayerToolbar.toString()})(window,{title:payload.title,author:payload.author,home:payload.homeUrl,status:'Starting game…',onOpen:()=>clientHost?.command('pause-input'),onClose:()=>clientHost?.command('resume-input')});document.body.prepend(toolbar.bar);
 const showSaveStatus=message=>toolbar.setStatus(message);
-async function mount(){clientHost?.close();if(saveHost)await saveHost.close();frame?.remove();frame=(${createFrame.toString()})(document,payload.document);saveHost=(${attachSaveHost.toString()})(window,frame,{...payload.saves,onStatus:value=>showSaveStatus(value.message)});clientHost=(${attachClientHost.toString()})(window,frame,(${recordAudio.toString()}),(${createExportStorage.toString()})(window,payload.saves),(${createExportsViewer.toString()}),(${recordVideo.toString()}),(${createPlayerToolbar.toString()}),{toolbar,htmlId:'portable-html-copy',zipId:'portable-copy',profile:(${createPlayerIdentity.toString()})().profile(window)});document.body.appendChild(frame);}
+const editGame=getArchive=>{showSaveStatus('Opening Studio…');return (${openGameInStudio.toString()})(window,getArchive,payload.studioUrl).then(()=>showSaveStatus('Editable copy saved in Studio'));};
+async function mount(){clientHost?.close();if(saveHost)await saveHost.close();frame?.remove();frame=(${createFrame.toString()})(document,payload.document);saveHost=(${attachSaveHost.toString()})(window,frame,{...payload.saves,onStatus:value=>showSaveStatus(value.message)});clientHost=(${attachClientHost.toString()})(window,frame,(${recordAudio.toString()}),(${createExportStorage.toString()})(window,payload.saves),(${createExportsViewer.toString()}),(${recordVideo.toString()}),(${createPlayerToolbar.toString()}),{toolbar,editGame,htmlId:'portable-html-copy',zipId:'portable-copy',profile:(${createPlayerIdentity.toString()})().profile(window)});document.body.appendChild(frame);}
 const fallback=(bytes,type,name)=>{const url=URL.createObjectURL(new Blob([bytes],{type}));const a=document.createElement('a');a.href=url;a.download=name;a.click();setTimeout(()=>URL.revokeObjectURL(url),30000);};
 toolbar.setAction('download-html',{label:'Download game HTML',id:'portable-html-copy',run:()=>fallback(originalHtml,'text/html',payload.name.replace(/\\.zip$/,'.html'))});
 toolbar.setAction('download-zip',{label:'Download game ZIP',id:'portable-copy',run:()=>fallback(Uint8Array.from(atob(payload.archive),c=>c.charCodeAt(0)),'application/zip',payload.name)});
+toolbar.setAction('edit-game',{label:'Edit this game',id:'edit-game',run:()=>editGame(()=>Uint8Array.from(atob(payload.archive),c=>c.charCodeAt(0)))});
 toolbar.setAction('save-download',{label:'Download save',id:'portable-save-download',run:()=>saveHost.downloadSave(payload.name.replace(/\\.zip$/,'-save.json'))});
 toolbar.setAction('save-import',{label:'Load save',id:'portable-save-import',run:()=>document.getElementById('portable-save-file').click()});
 mount();

package/portable-project.js

@@ -317,5 +317,26 @@ function checkSyntax(source) {
     catch (error) { return { message: error.message, line: error.loc?.line || 1 }; }
 }
 
-module.exports = { checkSyntax, MANIFEST, INVENTORY, LIMITS, normalizePath, resolveModule, canonical,
+// Library artwork is read from the entry's literal metadata, even when an
+// unrelated project file is unfinished. Never run game code to find an image.
+function thumbnailPath(files) {
+    try {
+        const manifest = json(bytes(files[MANIFEST]), MANIFEST), entry = normalizePath(manifest.entry);
+        const source = bytes(files[entry]);if(source.length > LIMITS.sourceBytes)return null;
+        const tree = acorn.parse(text(source), { ecmaVersion: 'latest', sourceType: 'script' });
+        const methods = [], bindings = new Map();
+        walk(tree, node => { if(node.type === 'MethodDefinition' && node.static && !node.computed && (node.key.name ?? node.key.value) === 'metadata')methods.push(node); });
+        const body = methods[0]?.value.body.body;
+        if(methods.length !== 1 || body.length !== 1 || body[0].type !== 'ReturnStatement' || body[0].argument?.type !== 'ObjectExpression')return null;
+        for(const statement of tree.body)if(statement.type === 'VariableDeclaration' && statement.kind === 'const') {
+            for(const declaration of statement.declarations)if(declaration.id.type === 'Identifier')bindings.set(declaration.id.name, declaration.init);
+        }
+        const property = body[0].argument.properties.find(prop => prop.type === 'Property' && !prop.computed && !prop.method && prop.kind === 'init' && (prop.key.name ?? prop.key.value) === 'thumbnail');
+        if(!property)return null;
+        const path = normalizePath(literal(property.value, 'thumbnail', bindings));
+        return own(files, path) ? path : null;
+    } catch (_) { return null; }
+}
+
+module.exports = { checkSyntax, thumbnailPath, MANIFEST, INVENTORY, LIMITS, normalizePath, resolveModule, canonical,
     createProject, exportArchive, importArchive, assetBundle };

package/portable-runtime.js

@@ -55,6 +55,7 @@ function prepareTrustedLocalGame(project, squishMap, { trusted = false, installa
     if (typeof installationId !== 'string' || !/^[a-zA-Z0-9-]{16,80}$/.test(installationId)) throw new Error('A trusted local installation ID is required for project saves');
     return {
         name: project.metadata.name || 'Homegame',
+        author: project.metadata.author || project.metadata.createdBy,
         gameClass: loadTrustedGame(project, squishMap, { trusted }),
         // No authored media means no packet. RTC correctly rejects zero-byte
         // packets; uploads can still register assets later in the session.

package/portable-saves.js

@@ -19,6 +19,7 @@ function attachSaveHost(window, frame, settings) {
     };
     const envelope = (data, schema = versionId) => ({ gameKey, gameId, versionId: schema, savedAt: Date.now(), data: clean(data) });
     function database() {
+        if (settings.database) return Promise.resolve(settings.database);
         if (!dbPromise) dbPromise = new Promise((resolve, reject) => {
             let blocked = false;
             const request = window.indexedDB.open('homegames-portable-saves', 1);
@@ -67,7 +68,7 @@ function attachSaveHost(window, frame, settings) {
         if (storageFailure) throw storageFailure;
         const db=await database(), next=latest;
         await new Promise((resolve,reject) => {
-            const tx=db.transaction('saves','readwrite'),store=tx.objectStore('saves');let error;
+            const tx=settings.transaction ? settings.transaction(['saves']) : db.transaction('saves','readwrite'),store=tx.objectStore('saves');let error;
             const request=store.get([installationId,versionId]);
             request.onsuccess=()=>{
                 try {

package/studio-debug.js

@@ -0,0 +1,91 @@
+'use strict';
+// Studio-only debugging across the opaque player boundary. The game never gets
+// access to the editor, its storage, or executable callbacks in the parent.
+function inspectorTree(value) {
+    let count = 0;
+    const number = value => Number.isFinite(value) ? value : 0;
+    const point = value => ({x:number(value?.x), y:number(value?.y)});
+    function walk(node, depth) {
+        if (!node || typeof node !== 'object' || depth > 48 || ++count > 4000) return null;
+        const result = {id:typeof node.id === 'number' ? node.id : String(node.id).slice(0,100), children:[]};
+        if (Array.isArray(node.coordinates2d)) result.coordinates2d = node.coordinates2d.slice(0,512).filter(p=>Array.isArray(p)&&p.length>=2).map(p=>[number(p[0]),number(p[1])]);
+        if (Array.isArray(node.fill)) result.fill = node.fill.slice(0,4).map(number);
+        if (node.text) result.text = {...point(node.text),text:String(node.text.text||'').slice(0,2000),size:number(node.text.size),align:String(node.text.align||'').slice(0,20)};
+        if (node.asset) result.asset = {key:String(node.asset.key||'').slice(0,200),pos:point(node.asset.pos),size:point(node.asset.size)};
+        if (Array.isArray(node.playerIds)) result.playerIds = node.playerIds.slice(0,64).filter(Number.isFinite);
+        if (node.clickable) result.clickable = true;
+        if (node.input) result.input = String(node.input).slice(0,100);
+        if (Array.isArray(node.children)) for (const child of node.children) { if(count>=4000)break;const next=walk(child,depth+1);if(next)result.children.push(next); }
+        return result;
+    }
+    return Array.isArray(value) ? value.slice(0,128).map(node=>walk(node,0)).filter(Boolean) : [];
+}
+function attachStudioDebugHost(window, frame, {onReady=()=>{},onError=()=>{},onLog=()=>{}} = {}) {
+    let port, closed=false, sequence=0, playerId=1, snapshot, input, pick;
+    const pending=new Map();
+    function request(action,value) {
+        if(!port||closed)return Promise.reject(new Error('Preview debugger is not ready'));
+        return new Promise((resolve,reject)=>{
+            const id=++sequence,timer=setTimeout(()=>{pending.delete(id);reject(new Error('Preview debugger timed out'));},5000);
+            pending.set(id,{resolve,reject,timer});port.postMessage({id,action,value});
+        });
+    }
+    const command=(action,value)=>{request(action,value).catch(error=>{if(!closed)onError(error);});};
+    function connect(event) {
+        if(closed||port||event.source!==frame.contentWindow||event.origin!=='null'||event.data?.type!=='homegames-studio-debug-v1')return;
+        const channel=new window.MessageChannel();port=channel.port1;
+        port.onmessage=({data})=>{
+            if(closed||!data)return;
+            if(data.event==='ready'){playerId=Number.isFinite(data.playerId)?data.playerId:1;onReady(data.available===true);}
+            else if(data.event==='snapshot'&&snapshot&&Number.isFinite(data.time)&&Number.isSafeInteger(data.frame))snapshot({time:data.time,buf:data.frame,tree:inspectorTree(data.tree)});
+            else if(data.event==='input'&&input&&Number.isFinite(data.value?.time))input({time:data.value.time,type:String(data.value.type||'').slice(0,40),key:String(data.value.key||'').slice(0,80)});
+            else if(data.event==='pick'&&pick){const x=data.x===null?null:Number(data.x),y=data.y===null?null:Number(data.y);if((x===null||Number.isFinite(x))&&(y===null||Number.isFinite(y))){if(data.kind==='select'){const callback=pick.onPick;pick=null;callback?.(x,y);}else pick.onMove?.(x,y);}}
+            else if(data.event==='log'&&['log','warn','error'].includes(data.level))onLog(data.level,String(data.message).slice(0,4000));
+            else if(data.event==='result'){const entry=pending.get(data.id);if(!entry)return;pending.delete(data.id);clearTimeout(entry.timer);data.error?entry.reject(new Error(String(data.error).slice(0,500))):entry.resolve(data.value);}
+        };
+        frame.contentWindow.postMessage({type:'homegames-studio-debug-port-v1'},'*',[channel.port2]);
+    }
+    window.addEventListener('message',connect);
+    return {
+        embedded:true,get playerId(){return playerId;},
+        enableInspector(onSnapshot,onInput){snapshot=onSnapshot;input=onInput;command('inspect',true);},
+        disableInspector(){snapshot=input=pick=null;command('inspect',false);},
+        showFrame:id=>command('frame',id),resumeLive:()=>command('live'),setHighlight:points=>command('highlight',points),
+        enablePick(callbacks){pick=callbacks;command('pick',true);},disablePick(){pick=null;command('pick',false);},
+        addPlayer:()=>request('add-player'),removePlayer:id=>command('remove-player',id),freeze:()=>command('freeze'),
+        stop(){if(closed)return;closed=true;window.removeEventListener('message',connect);port?.close();snapshot=input=pick=null;for(const entry of pending.values()){clearTimeout(entry.timer);entry.reject(new Error('Preview closed'));}pending.clear();}
+    };
+}
+function connectStudioDebugSource(window, getSession) {
+    const document=window.document,frames=new Map();
+    let port,closed=false,available=false,frameId=0,frameBytes=0,secondId=null,secondView,firstLabel;
+    const send=data=>{if(!closed&&port)port.postMessage(data);};
+    const resize=()=>window.dispatchEvent(new window.Event('resize'));
+    function removePlayer(session) {if(secondId!==null)session?.removePlayer(secondId);secondId=null;secondView?.remove();secondView=null;firstLabel?.remove();firstLabel=null;resize();}
+    const label=(container,text)=>{const el=document.createElement('span');el.textContent=text;el.style.cssText='position:absolute;left:8px;top:6px;z-index:2;background:#101820cc;color:#fff;padding:3px 6px;border-radius:4px;font:12px system-ui;pointer-events:none';container.style.position='relative';container.append(el);return el;};
+    const commands={
+        inspect(session,enabled){frames.clear();frameBytes=0;if(!enabled){session.disableInspector();return;}
+            session.enableInspector(snap=>{if(!snap.buf?.byteLength||snap.buf.byteLength>8*1024*1024)return;const id=++frameId;frames.set(id,snap.buf.slice());frameBytes+=snap.buf.byteLength;while(frames.size>600||frameBytes>64*1024*1024){const oldest=frames.keys().next().value;frameBytes-=frames.get(oldest).byteLength;frames.delete(oldest);}send({event:'snapshot',frame:id,time:snap.time,tree:inspectorTree(snap.tree)});},value=>send({event:'input',value}));},
+        frame(session,id){const buf=frames.get(id);if(!buf)throw new Error('This recorded frame is no longer available');session.showFrame(buf);},
+        live:session=>session.resumeLive(),highlight:(session,value)=>session.setHighlight(value),
+        pick(session,enabled){if(!enabled){session.disablePick();return;}session.enablePick({onMove:(x,y)=>send({event:'pick',kind:'move',x,y}),onPick:(x,y)=>send({event:'pick',kind:'select',x,y})});},
+        'add-player'(session){if(secondId!==null)return secondId;if(session.frozen)throw new Error('Restart the game before adding a player');
+            const game=document.getElementById('game');secondView=document.createElement('div');secondView.id='studio-debug-player-2';secondView.style.cssText='flex:1;min-height:0;display:flex;align-items:center;justify-content:center;overflow:hidden;border-top:1px solid #45546a';game.after(secondView);resize();
+            secondId=session.addPlayer(secondView.id);if(secondId===null){removePlayer(session);throw new Error('Could not add a player');}
+            firstLabel=label(game,'Player '+session.playerId);label(secondView,'Player '+secondId);resize();return secondId;},
+        'remove-player':session=>removePlayer(session),freeze(session){removePlayer(session);session.freeze();}
+    };
+    function connect(event){
+        if(closed||port||event.source!==window.parent||event.data?.type!=='homegames-studio-debug-port-v1'||!event.ports[0])return;
+        window.removeEventListener('message',connect);port=event.ports[0];
+        port.onmessage=({data})=>{if(closed||!data||!Number.isSafeInteger(data.id))return;
+            try {const session=getSession();if(!session)throw new Error('Debug tools require a local game');if(!Object.hasOwn(commands,data.action))throw new Error('Unknown debug action');const value=commands[data.action](session,data.value);send({event:'result',id:data.id,value});}
+            catch(error){send({event:'result',id:data.id,error:error.message});}
+        };send({event:'ready',available,playerId:getSession()?.playerId});
+    }
+    window.addEventListener('message',connect);window.parent.postMessage({type:'homegames-studio-debug-v1'},'*');
+    const originals={},wrappers={};let logWindow=0,logs=0;
+    for(const level of ['log','warn','error']){originals[level]=window.console[level];wrappers[level]=(...args)=>{originals[level].apply(window.console,args);const now=Date.now();if(now-logWindow>1000){logs=0;logWindow=now;}if(++logs>25)return;const message=args.map(value=>{try{return typeof value==='string'?value:JSON.stringify(value);}catch(_){return String(value);}}).join(' ').slice(0,4000);send({event:'log',level,message});};window.console[level]=wrappers[level];}
+    return {ready(){available=!!getSession();send({event:'ready',available,playerId:getSession()?.playerId});},close(){if(closed)return;closed=true;window.removeEventListener('message',connect);getSession()?.disableInspector();removePlayer(getSession());frames.clear();port?.close();for(const level of Object.keys(originals))if(window.console[level]===wrappers[level])window.console[level]=originals[level];}};
+}
+module.exports={inspectorTree,attachStudioDebugHost,connectStudioDebugSource};

package/studio-handoff.js

@@ -0,0 +1,79 @@
+'use strict';
+
+// Self-contained: the sender is also embedded in standalone HTML. Project
+// bytes travel between these two windows, never in a URL or server request.
+function openGameInStudio(window, getArchive, studioUrl = 'https://homegames.io/studio.html') {
+    const url = new URL(studioUrl);
+    if (!['https:', 'http:'].includes(url.protocol) || url.username || url.password) throw new Error('Invalid Studio address');
+    const token = window.crypto.randomUUID(), origin = url.origin;
+    // Browsers serialize file message origins as either "null" or "file://".
+    url.hash = new URLSearchParams({ edit: token, from: window.location.protocol === 'file:' ? 'file://' : window.location.origin }).toString();
+    return new Promise((resolve, reject) => {
+        let target, archive, sending = false, finished = false;
+        const finish = error => {
+            if (finished) return; finished = true;
+            clearTimeout(timer); clearInterval(closed);
+            window.removeEventListener('message', receive); window.removeEventListener('pagehide', leaving);
+            error ? reject(error) : resolve();
+        };
+        const leaving = () => finish(new Error('Keep the game open until Studio receives it.'));
+        const receive = event => {
+            if (finished || !target || event.source !== target || event.origin !== origin || event.data?.token !== token) return;
+            if (event.data.type === 'homegames-studio-saved') return finish();
+            if (event.data.type === 'homegames-studio-error') return finish(new Error(String(event.data.error).slice(0, 300)));
+            if (event.data.type !== 'homegames-studio-ready' || sending) return;
+            sending = true;
+            archive ||= Promise.resolve().then(getArchive).then(bytes => {
+                if (!(bytes instanceof Uint8Array) || !bytes.length || bytes.length > 65 * 1024 * 1024) throw new Error('Invalid game archive');
+                return bytes;
+            });
+            archive.then(bytes => {
+                if (!finished) target.postMessage({ type: 'homegames-studio-game', token, bytes }, origin);
+                sending = false;
+            }).catch(finish);
+        };
+        const timer = setTimeout(() => finish(new Error('Studio did not receive the game. Open Studio online once, or import the game HTML or ZIP there.')), 90000);
+        const closed = setInterval(() => { if (target?.closed) finish(new Error('Studio was closed before saving the copy.')); }, 500);
+        window.addEventListener('message', receive); window.addEventListener('pagehide', leaving);
+        try {
+            target = window.open(url.href, '_blank');
+            if (!target) finish(new Error('Allow this game to open a Studio tab, or import its HTML or ZIP in Studio.'));
+        } catch (error) { finish(error); }
+    });
+}
+
+function receiveGameInStudio(window, saveArchive) {
+    const params = new URLSearchParams(window.location.hash.slice(1));
+    const token = params.get('edit'), origin = params.get('from'), source = window.opener;
+    const localFile = origin === 'file://';
+    if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(token || '') || !source) return Promise.reject(new Error('Reopen Edit this game from the player, or import its HTML or ZIP.'));
+    try {
+        if (origin !== 'null' && !localFile && (!['http:', 'https:'].includes(new URL(origin).protocol) || new URL(origin).origin !== origin)) throw new Error();
+    } catch (_) { return Promise.reject(new Error('Invalid game sender')); }
+    return new Promise((resolve, reject) => {
+        let receiving = false, finished = false;
+        const send = data => { try { source.postMessage({ ...data, token }, origin === 'null' || localFile ? '*' : origin); } catch (_) { /* Sender may have closed. */ } };
+        const finish = (error, value) => {
+            if (finished) return; finished = true;
+            clearTimeout(timer); clearInterval(ping); window.removeEventListener('message', receive); window.removeEventListener('pagehide', leaving);
+            if (error) { send({ type: 'homegames-studio-error', error: error.message }); reject(error); }
+            else { send({ type: 'homegames-studio-saved' }); resolve(value); }
+        };
+        const leaving = () => finish(new Error('Studio closed before receiving the game.'));
+        const receive = event => {
+            if (finished || receiving || event.source !== source || (localFile ? !['null', 'file://'].includes(event.origin) : event.origin !== origin)
+                || event.data?.token !== token || event.data.type !== 'homegames-studio-game') return;
+            const bytes = event.data.bytes;
+            if (!(bytes instanceof Uint8Array) || !bytes.length || bytes.length > 65 * 1024 * 1024) return finish(new Error('Invalid game archive'));
+            receiving = true; clearInterval(ping); clearTimeout(timer);
+            // The caller validates and persists the archive as data before ACK.
+            Promise.resolve().then(() => saveArchive(bytes)).then(value => finish(null, value), finish);
+        };
+        const ready = () => send({ type: 'homegames-studio-ready' });
+        const timer = setTimeout(() => finish(new Error('The game did not arrive. Keep its tab open and try Edit this game again.')), 90000);
+        const ping = setInterval(ready, 500);
+        window.addEventListener('message', receive); window.addEventListener('pagehide', leaving); ready();
+    });
+}
+
+module.exports = { openGameInStudio, receiveGameInStudio };

package/test/player-toolbar.test.cjs

@@ -0,0 +1,65 @@
+'use strict';
+const test = require('node:test'), assert = require('node:assert/strict');
+const { createPlayerToolbar } = require('../player-toolbar');
+function windowWithDom() {
+    class Element {
+        constructor(tag) { this.tagName = tag; this.children = []; this.attributes = {}; }
+        setAttribute(name, value) { this.attributes[name] = value; }
+        append(...children) { children.forEach(child => { child.remove(); this.children.push(child); child.parent = this; }); }
+        prepend(child) { child.remove(); this.children.unshift(child); child.parent = this; }
+        insertBefore(child, sibling) { child.remove(); this.children.splice(this.children.indexOf(sibling), 0, child); child.parent = this; }
+        remove() { if (this.parent) this.parent.children = this.parent.children.filter(child => child !== this); }
+        addEventListener() {}
+        click() { if (!this.disabled) this.onclick?.(); }
+    }
+    return { document: { body: new Element('body'), createElement: tag => new Element(tag) } };
+}
+test('website and embedded toolbar keep common primary actions and preserve popup gestures', async () => {
+    const toolbarFactory = (0, eval)('(' + createPlayerToolbar.toString() + ')');
+    for (const simple of [false, true]) {
+        const toolbar = toolbarFactory(windowWithDom(), { home: '/catalog.html', title: 'Test game', author: 'A developer', simple });
+        const home = toolbar.bar.children.find(child => child.attributes['aria-label'] === 'Home');
+        assert.equal(home.href, '/catalog.html');
+        assert.match(home.children[0].src, /^data:image\/png;base64,/);
+        const heading = toolbar.bar.children.find(child => child.className === 'hg-player-heading');
+        const [title, website] = heading.children[0].children;
+        assert.equal(title.children[0].textContent, 'Test game');
+        assert.equal(title.children[1].textContent, ' by A developer');
+        assert.equal(website.textContent, 'homegames.io');
+        assert.equal(website.href, 'https://homegames.io/');
+        assert.equal(website.target, '_blank');
+        assert.equal(website.rel, 'noopener noreferrer');
+        toolbar.setTitle('Renamed game');
+        assert.equal(title.children[1].textContent, ' by A developer', 'Title updates retain the author and website link');
+        toolbar.setAuthor(''); assert.equal(title.children[1].hidden, true);
+        let clicked = 0, resolve;
+        toolbar.setAction('download-html', { label: 'Download game HTML', run() {} });
+        toolbar.setAction('exports', { label: 'View exports', run() {} });
+        const edit = { label: 'Edit this game', run() { clicked++; return new Promise(done => { resolve = done; }); } };
+        toolbar.setAction('edit-game', edit);
+        const button = toolbar.bar.children.find(child => child.attributes['aria-label'] === 'Edit this game');
+        assert.ok(button && !button.hidden);
+        assert.ok(toolbar.bar.children.some(child => child.textContent === 'Download file' && !child.hidden));
+        let installs = 0;
+        toolbar.setAction('install', { label: 'Download app', run() { installs++; } });
+        assert.ok(toolbar.bar.children.some(child => child.textContent === 'Download app' && !child.hidden));
+        assert(!toolbar.bar.children.some(child => child.textContent === 'Download file'));
+        const menuActions = toolbar.menu.children.find(child => child.className === 'hg-player-menu-actions');
+        assert(menuActions.children.some(child => child.textContent === 'Download game file (HTML)' && !child.hidden));
+        toolbar.runAction('install'); assert.equal(installs, 1, 'Native install prompts retain the click gesture');
+        toolbar.setAction('download-html', { label: 'Download game HTML', run() {} });
+        assert(menuActions.children.some(child => child.textContent === 'Download game file (HTML)' && !child.hidden), 'Player-ready updates retain the portable download');
+        toolbar.setAction('install', null);
+        assert.ok(toolbar.bar.children.some(child => child.textContent === 'Download file' && !child.hidden));
+        assert.equal(toolbar.bar.children.some(child => child.textContent === 'View exports'), false);
+        assert.equal(toolbar.runAction('edit-game'), true);
+        assert.equal(clicked, 1, 'The popup callback runs within the click, before yielding');
+        assert.equal(button.disabled, true);
+        toolbar.setAction('edit-game', edit); // A player-state update must not permit duplicate clicks.
+        assert.equal(toolbar.runAction('edit-game'), false);
+        resolve(); await new Promise(done => setImmediate(done));
+        assert.equal(button.disabled, false);
+        toolbar.setAction('edit-game', null); assert.equal(button.hidden, true);
+        toolbar.dispose();
+    }
+});

package/test/portable-downloads.test.cjs

@@ -0,0 +1,48 @@
+'use strict';
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const { attachClientHost } = require('../portable-client');
+
+test('player downloads use the game title, honor a recovered name, and keep safe filenames', async t => {
+    const listeners = new Map(), actions = new Map(), downloads = [];
+    let source, nextTitle, resolveState, title, editedArchive;
+    const toolbar = { setTitle() {}, setPlayerName() {}, setAction(key, action) { actions.set(key, action); },
+        setStatus() { resolveState?.(); resolveState = null; } };
+    const frame = { style: {}, parentElement: { style: {} }, contentWindow: {
+        postMessage(message, origin, ports) {
+            source = ports[0];
+            source.onmessage = event => source.postMessage({ type: 'game-download', id: event.data.id, bytes: new Uint8Array([80, 75]) });
+        }
+    } };
+    const window = { MessageChannel, URL: { createObjectURL: () => 'blob:test', revokeObjectURL() {} },
+        document: { createElement: () => ({ click() { downloads.push(this.download); } }) },
+        addEventListener: (type, listener) => listeners.set(type, listener), removeEventListener: type => listeners.delete(type) };
+    // The production HTML embeds this function's source, so also exercise it
+    // without access to the module's lexical scope.
+    const attach = (0, eval)('(' + attachClientHost.toString() + ')');
+    const host = attach(window, frame, null, null, null, null, null, { toolbar, downloadName: () => title,
+        editGame: async getArchive => { editedArchive = await getArchive(); } });
+    t.after(() => { host.close(); source?.close(); });
+    listeners.get('message')({ source: frame.contentWindow, origin: 'null', data: { type: 'homegames-client-connect-v1' } });
+    const state = async value => {
+        nextTitle = new Promise(resolve => { resolveState = resolve; });
+        source.postMessage({ type: 'player-state', title: value, status: 'Playing', ready: true });
+        await nextTitle;
+    };
+    // Complete cleanup timers without waiting thirty seconds for each URL.
+    t.mock.timers.enable({ apis: ['setTimeout'] });
+    await state('Weed Smoke Willie');
+    await actions.get('edit-game').run();
+    assert.deepEqual(editedArchive, new Uint8Array([80, 75]), 'Edit requests the live runtime ZIP through the same bridge as downloads');
+    await actions.get('download-html').run();
+    await actions.get('download-zip').run();
+    assert.deepEqual(downloads.splice(0), ['weed-smoke-willie.html', 'weed-smoke-willie.zip']);
+    await state('Homegame'); title = 'Pocket Chime';
+    await host.download('html');
+    assert.equal(downloads.pop(), 'pocket-chime.html', 'A recovered catalog name wins over an older embedded title');
+    title = null;
+    for (const [name, expected] of [['../CON', 'con-game.html'], ['!!!', 'game.html'], ['X'.repeat(100), 'x'.repeat(80) + '.html']]) {
+        await state(name); await host.download('html'); assert.equal(downloads.pop(), expected);
+    }
+    t.mock.timers.tick(30000);
+});

package/test/portable-frame.test.cjs

@@ -0,0 +1,17 @@
+'use strict';
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const { createFrame } = require('../portable-html');
+
+test('catalog, Studio, and serialized offline frames explicitly allow gamepads while retaining opaque isolation', () => {
+    // Exported HTML embeds the function, so it must also work out of module scope.
+    for (const create of [createFrame, (0, eval)('(' + createFrame.toString() + ')')]) {
+        const frame = { attributes: {}, setAttribute(name, value) { this.attributes[name] = value; } };
+        const result = create({ createElement(tag) { assert.equal(tag, 'iframe'); return frame; } }, '<p>Game</p>');
+        assert.equal(result.srcdoc, '<p>Game</p>');
+        assert.match(result.attributes.allow, /(?:^|;\s*)gamepad \*(?:;|$)/);
+        assert.equal(result.attributes.sandbox, 'allow-scripts allow-pointer-lock');
+        assert.match(result.attributes.allow, /camera 'none'/);
+        assert.match(result.attributes.allow, /microphone 'none'/);
+    }
+});

package/test/standalone-edit.test.cjs

@@ -0,0 +1,23 @@
+'use strict';
+const test = require('node:test'), assert = require('node:assert/strict'), path = require('node:path');
+const { readDirectory, options } = require('../portable-project-node');
+const { createProject, importArchive } = require('../portable-project');
+const { buildIsolatedHtml, readHtmlArchive } = require('../portable-html');
+
+test('standalone HTML uses the shared edit control and preserves the full project as data', async () => {
+    const original = await readDirectory(path.resolve(__dirname, '../../homegames-core/test/fixtures/portable-sound'));
+    const files = Object.fromEntries(original.reader.listFiles().map(name => [name, original.reader.readFile(name)]));
+    files['user-exports/drawing.bin'] = new Uint8Array([0, 255, 10, 13, 128]);
+    const project = await createProject(files, options);
+    const html = await buildIsolatedHtml(project, { clientBundleSource: '/* PortableProject */ globalThis.wrapperExecuted=true;',
+        installationId: '12345678-1234-1234-1234-123456789012', sharing: { joinUrl: 'http://localhost:81/play.html' } });
+    const payload = JSON.parse(html.match(/<script id="homegames-project" type="application\/json">([\s\S]*?)<\/script>/)[1]);
+    assert.equal(payload.studioUrl, 'http://localhost:81/studio.html');
+    assert.equal(payload.homeUrl, 'http://localhost:81/catalog.html');
+    assert.match(html, /Edit this game/); assert.match(html, /homegames-studio-game/);
+    assert.match(payload.document, /studioUrl:payload.studioUrl/);
+    const copy = await importArchive(readHtmlArchive(html), options);
+    for (const name of project.reader.listFiles()) assert.deepEqual(copy.reader.readFile(name), project.reader.readFile(name), name);
+    assert.equal(globalThis.wrapperExecuted, undefined);
+    await assert.rejects(buildIsolatedHtml(project, { clientBundleSource: 'PortableProject', installationId: '1234567890123456', studioUrl: 'javascript:alert(1)' }), /Studio URL/);
+});

package/test/studio-debug.test.cjs

@@ -0,0 +1,69 @@
+'use strict';
+const test=require('node:test'),assert=require('node:assert/strict');
+const {inspectorTree,attachStudioDebugHost,connectStudioDebugSource}=require('../studio-debug');
+
+test('inspector trees are bounded data, even with deep, cyclic or malformed nodes',()=>{
+    const node={id:1,children:[],coordinates2d:[[1,2],[Infinity,3]],text:{text:'x'.repeat(3000),size:5}};node.children.push(node);
+    const tree=inspectorTree([node]);let depth=0,current=tree[0];while(current){depth++;current=current.children[0];}
+    assert.equal(depth,49);assert.equal(tree[0].text.text.length,2000);assert.deepEqual(tree[0].coordinates2d,[[1,2],[0,3]]);
+    assert.deepEqual(inspectorTree(null),[]);
+});
+
+test('isolated Studio debug bridge restores inspection, picking, player views and cleanup',async t=>{
+    class Element {
+        constructor(tag){this.tagName=tag;this.children=[];this.style={};}
+        append(child){this.children.push(child);child.parent=this;}
+        after(child){this.parent.append(child);}
+        remove(){if(this.parent)this.parent.children=this.parent.children.filter(child=>child!==this);}
+    }
+    const body=new Element('body'),game=new Element('div');game.id='game';body.append(game);
+    const doc={body,createElement:tag=>new Element(tag),getElementById:id=>body.children.find(el=>el.id===id)};
+    const hostListeners=new Map(),sourceListeners=new Map(),errors=[],calls=[],logs=[];
+    const session={playerId:7,enableInspector(s,i){this.snapshot=s;this.input=i;},disableInspector(){this.snapshot=null;},
+        showFrame:buf=>calls.push(['frame',[...buf]]),resumeLive:()=>calls.push(['live']),setHighlight:value=>calls.push(['highlight',value]),
+        enablePick(callbacks){this.pick=callbacks;},disablePick(){this.pick=null;},
+        addPlayer:id=>{calls.push(['add',id]);return 8;},removePlayer:id=>calls.push(['remove',id]),freeze(){this.frozen=true;calls.push(['freeze']);}};
+    let readyResolve,snapshotResolve,pickResolve;
+    const ready=new Promise(resolve=>readyResolve=resolve);
+    const parent={postMessage:data=>hostListeners.get('message')?.({source:child,origin:'null',data})};
+    const child={document:doc,parent,Event:class{constructor(type){this.type=type;}},dispatchEvent(){},console:{log(){},warn(){},error(){}},
+        addEventListener:(type,fn)=>sourceListeners.set(type,fn),removeEventListener:type=>sourceListeners.delete(type),
+        postMessage:(data,origin,ports)=>sourceListeners.get('message')?.({source:parent,data,ports})};
+    const hostWindow={MessageChannel,addEventListener:(type,fn)=>hostListeners.set(type,fn),removeEventListener:type=>hostListeners.delete(type)};
+    const frame={contentWindow:child};
+    const host=attachStudioDebugHost(hostWindow,frame,{onReady:value=>{if(value)readyResolve(value);},onError:e=>errors.push(e),onLog:(level,message)=>logs.push([level,message])});
+    // A different frame cannot connect a debugging channel.
+    hostListeners.get('message')({source:{},origin:'null',data:{type:'homegames-studio-debug-v1'}});
+    const source=connectStudioDebugSource(child,()=>session);source.ready();
+    t.after(()=>{host.stop();source.close();});
+    assert.equal(await ready,true);assert.equal(host.playerId,7);
+    const snapshot=new Promise(resolve=>snapshotResolve=resolve);
+    host.enableInspector(value=>snapshotResolve(value));
+    child.console.warn('Preview warning', {count:2});
+    assert.equal(await host.addPlayer(),8); // Ordered acknowledgement also flushes inspect.
+    assert.ok(doc.getElementById('studio-debug-player-2'));
+    assert.deepEqual(logs,[['warn','Preview warning {"count":2}']]);
+    session.snapshot({time:100,buf:new Uint8Array([1,2,3]),tree:[{id:2,clickable:true,children:[]}]});
+    const recorded=await snapshot;assert.equal(typeof recorded.buf,'number');assert.equal(recorded.tree[0].id,2);
+    host.showFrame(recorded.buf);host.setHighlight([[0,0],[10,0],[10,10]]);
+    const picked=new Promise(resolve=>pickResolve=resolve);
+    host.enablePick({onPick:(x,y)=>pickResolve([x,y])});await host.addPlayer();
+    session.pick.onPick(20,30);assert.deepEqual(await picked,[20,30]);
+    host.freeze();await assert.rejects(host.addPlayer(),/Restart/);
+    assert.ok(calls.some(call=>call[0]==='frame'&&call[1].join(',')==='1,2,3'));
+    assert.ok(calls.some(call=>call[0]==='remove'&&call[1]===8));
+    assert.ok(calls.some(call=>call[0]==='freeze'));
+    host.stop();await assert.rejects(host.addPlayer(),/not ready/);
+    assert.equal(hostListeners.has('message'),false);assert.deepEqual(errors,[]);
+});
+
+test('Studio debugging is opt-in and exported game documents do not enable it',async()=>{
+    const path=require('node:path'),{readDirectory}=require('../portable-project-node');
+    const {runtimeDocument,buildIsolatedHtml}=require('../portable-html');
+    const project=await readDirectory(path.resolve(__dirname,'../../homegames-core/test/fixtures/portable-sound'));
+    const options={clientBundleSource:'/* PortableProject */',installationId:'12345678-1234-1234-1234-123456789012'};
+    const studio=await runtimeDocument(project,{...options,studioDebug:true});assert.match(studio,/"studioDebug":true/);
+    const standalone=await buildIsolatedHtml(project,options);
+    const payload=JSON.parse(standalone.match(/<script id="homegames-project" type="application\/json">([\s\S]*?)<\/script>/)[1]);
+    assert.match(payload.document,/"studioDebug":false/);
+});

package/test/studio-handoff.test.cjs

@@ -0,0 +1,94 @@
+'use strict';
+const test = require('node:test'), assert = require('node:assert/strict');
+const { randomUUID } = require('node:crypto');
+const { openGameInStudio, receiveGameInStudio } = require('../studio-handoff');
+const send = (0, eval)('(' + openGameInStudio.toString() + ')'); // Also runs embedded in HTML.
+const tick = () => new Promise(resolve => setImmediate(resolve));
+function pair(origin = 'null', protocol = 'https:') {
+    function endpoint(location) {
+        const events = new Map();
+        return { location, crypto: { randomUUID },
+            addEventListener(type, fn) { events.set(type, fn); },
+            removeEventListener(type) { events.delete(type); },
+            emit(type, event) { events.get(type)?.(event); },
+            get listenerCount() { return events.size; } };
+    }
+    const game = endpoint({ origin, protocol }), studio = endpoint({ origin: 'https://studio.example' });
+    const traffic = [];
+    const gameRef = { postMessage(data, target) {
+        traffic.push({ direction: 'game', data, target });
+        assert.ok(target === '*' || target === origin);
+        queueMicrotask(() => game.emit('message', { data, origin: studio.location.origin, source: studioRef }));
+    } };
+    const studioRef = { closed: false, postMessage(data, target) {
+        traffic.push({ direction: 'studio', data, target });
+        assert.equal(target, studio.location.origin);
+        queueMicrotask(() => studio.emit('message', { data, origin, source: gameRef }));
+    } };
+    game.open = url => { studio.location.hash = new URL(url).hash; return studioRef; };
+    studio.opener = gameRef;
+    return { game, studio, gameRef, studioRef, traffic };
+}
+
+for (const [protocol, origin] of [['file:', 'null'], ['file:', 'file://'], ['https:', 'https://game.example']]) test(`complete archive travels directly from ${origin} and is acknowledged after persistence`, async () => {
+    const ctx = pair(origin, protocol), bytes = new Uint8Array([80, 75, 0, 255, 7]);
+    let getCount = 0, saved = false, release, imports = 0;
+    const sent = send(ctx.game, () => { getCount++; return bytes; }, 'https://studio.example/studio.html').then(() => { saved = true; });
+    const received = receiveGameInStudio(ctx.studio, async value => {
+        imports++; assert.deepEqual(value, bytes);
+        await new Promise(resolve => { release = resolve; }); return 'project';
+    });
+    await tick();
+    assert.equal(saved, false);
+    const packet = ctx.traffic.find(item => item.direction === 'studio').data;
+    ctx.studioRef.postMessage(packet, ctx.studio.location.origin); // Duplicate delivery must not create a second project.
+    await tick(); assert.equal(imports, 1); release();
+    assert.equal(await received, 'project'); await sent;
+    assert.equal(getCount, 1); assert.equal(saved, true);
+    assert.equal(ctx.game.listenerCount + ctx.studio.listenerCount, 0);
+    assert.ok(!ctx.studio.location.hash.includes('bytes'));
+});
+
+test('unrelated windows, origins, and tokens cannot inject an archive or acknowledge a transfer', async () => {
+    const ctx = pair(), bytes = new Uint8Array([1]); let imports = 0;
+    const sent = send(ctx.game, () => bytes, 'https://studio.example/studio.html');
+    const token = new URLSearchParams(ctx.studio.location.hash.slice(1)).get('edit');
+    const valid = { source: ctx.gameRef, origin: 'null', data: { type: 'homegames-studio-game', token, bytes } };
+    const received = receiveGameInStudio(ctx.studio, () => { imports++; });
+    for (const patch of [{ source: {} }, { origin: 'https://evil.example' }, { data: { ...valid.data, token: randomUUID() } }]) {
+        ctx.studio.emit('message', { ...valid, ...patch });
+    }
+    assert.equal(imports, 0);
+    await received; await sent; assert.equal(imports, 1);
+});
+
+test('failed persistence reaches the sender and releases both sides', async () => {
+    const ctx = pair();
+    const sent = assert.rejects(send(ctx.game, () => new Uint8Array([1]), 'https://studio.example/studio.html'), /storage full/);
+    const received = assert.rejects(receiveGameInStudio(ctx.studio, () => { throw new Error('storage full'); }), /storage full/);
+    await Promise.all([sent, received]);
+    assert.equal(ctx.game.listenerCount + ctx.studio.listenerCount, 0);
+});
+
+test('popup blocking and archive failures keep a usable recovery error', async () => {
+    const blocked = pair(); blocked.game.open = () => null;
+    await assert.rejects(send(blocked.game, () => {}), /import its HTML or ZIP/);
+    assert.equal(blocked.game.listenerCount, 0);
+    const ctx = pair();
+    const sent = assert.rejects(send(ctx.game, () => { throw new Error('Copy failed'); }, 'https://studio.example/studio.html'), /Copy failed/);
+    const received = receiveGameInStudio(ctx.studio, () => {});
+    const caught = assert.rejects(received, /closed/);
+    await sent; ctx.studio.emit('pagehide'); await caught;
+    assert.equal(ctx.game.listenerCount + ctx.studio.listenerCount, 0);
+});
+
+test('timeout and closed tabs clean up pending transfers', async t => {
+    t.mock.timers.enable({ apis: ['setTimeout', 'setInterval'] });
+    const ctx = pair();
+    const sent = assert.rejects(send(ctx.game, () => {}, 'https://studio.example/studio.html'), /did not receive/);
+    t.mock.timers.tick(90000); await sent; assert.equal(ctx.game.listenerCount, 0);
+    const closed = pair();
+    const pending = assert.rejects(send(closed.game, () => {}, 'https://studio.example/studio.html'), /closed/);
+    closed.studioRef.closed = true; t.mock.timers.tick(500); await pending;
+    assert.equal(closed.game.listenerCount, 0);
+});

package/test/studio-thumbnail.test.cjs

@@ -0,0 +1,21 @@
+'use strict';
+const test = require('node:test'), assert = require('node:assert/strict');
+const { thumbnailPath } = require('../portable-project');
+const project = source => ({'homegame.json':JSON.stringify({entry:'index.js'}),'index.js':source,
+    'assets/cover.png':new Uint8Array([137,80,78,71]),'unfinished.js':'class {'});
+
+test('Studio reads declared local artwork without evaluating game code or requiring other files to compile', () => {
+    const files = project("globalThis.thumbnailCodeRan = true; const COVER = './assets/cover.png'; class Game { static metadata() { return {thumbnail:COVER}; } }");
+    assert.equal(thumbnailPath(files), 'assets/cover.png');
+    assert.equal(globalThis.thumbnailCodeRan, undefined);
+    assert.equal(thumbnailPath({...files,'index.js':new TextEncoder().encode(files['index.js'])}), 'assets/cover.png');
+});
+
+test('missing, unsafe, computed and unfinished thumbnail metadata falls back without executing it', () => {
+    for(const value of ["'https://example.com/cover.png'", "'../cover.png'", "'assets/missing.png'", '(globalThis.thumbnailCodeRan = true)']) {
+        assert.equal(thumbnailPath(project(`class Game { static metadata() { return {thumbnail:${value}}; } }`)), null);
+    }
+    assert.equal(thumbnailPath(project('class {')), null);
+    assert.equal(thumbnailPath({}), null);
+    assert.equal(globalThis.thumbnailCodeRan, undefined);
+});