homegames-common 1.7.0 → 1.7.2

package/portable-html.js

@@ -9,6 +9,8 @@ const { createExportsViewer } = require('./exports-viewer');
 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 => {
@@ -38,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');
@@ -46,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
@@ -60,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 {
@@ -71,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)
+'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});
-client=new HomegamesClient({containerId:'game',chrome:false,localHome:false,share:payload.sharing,saveStore,platform:clientSource,
+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:transport=>{client.stop();client=new HomegamesClient({containerId:'game',chrome:false,transport,platform:clientSource,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>`;
@@ -92,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;
@@ -104,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>
@@ -113,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'});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/);
+});