@pix3/vite-plugin 2.0.0-alpha.0 → 2.0.0-alpha.1

package/dist/player/dev/editor-link.js

@@ -0,0 +1,125 @@
+/**
+ * The "Pix3 editor" link over the game in dev (`virtual:pix3/dev`; not on `?clean`, not in a
+ * frame, not in a build). A second editor tab would open read-only (the writer lock), so the link
+ * first asks over a `BroadcastChannel` whether an editor of this dev server is open: if one
+ * answers, the page says so and tries to bring its opener forward; if none does, this tab becomes
+ * the editor. The editor answers in `packages/editor-core/src/host/editor-presence.ts`.
+ */
+/** Keep in step with `editor-presence.ts` in editor-core. */
+export const EDITOR_PRESENCE_CHANNEL = 'pix3-editor-presence';
+const ANSWER_MS = 300;
+const HIDDEN_KEY = 'pix3:editor-link:hidden';
+/** True when an editor tab of this origin answers within {@link ANSWER_MS}. */
+export const isEditorOpen = (timeoutMs = ANSWER_MS) => new Promise(resolve => {
+    if (typeof BroadcastChannel === 'undefined') {
+        resolve(false);
+        return;
+    }
+    const channel = new BroadcastChannel(EDITOR_PRESENCE_CHANNEL);
+    const id = Math.random().toString(36).slice(2);
+    const done = (open) => {
+        clearTimeout(timer);
+        channel.close();
+        resolve(open);
+    };
+    const timer = setTimeout(() => done(false), timeoutMs);
+    channel.onmessage = event => {
+        const data = event.data;
+        if (data?.type === 'pong' && data.id === id)
+            done(true);
+    };
+    channel.postMessage({ type: 'ping', id });
+});
+/** Go to the editor: this tab becomes it, unless one is already open. */
+export const openEditor = async (editorUrl) => {
+    if (await isEditorOpen()) {
+        try {
+            // The editor opened this page (Play in Browser Tab / with Profiler): it is the opener.
+            window.opener?.focus();
+        }
+        catch {
+            // A cross-origin or severed opener: nothing to focus.
+        }
+        return 'already-open';
+    }
+    window.location.href = editorUrl;
+    return 'navigated';
+};
+const STYLE = `
+:host { all: initial; }
+.link {
+  position: fixed; left: 8px; bottom: 8px; z-index: 2147483646;
+  display: flex; align-items: center; gap: 2px;
+  font: 600 11px/1 ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif;
+  color: #e8e8e8; background: rgba(18, 18, 20, 0.72); border: 1px solid rgba(255,255,255,0.14);
+  border-radius: 999px; padding: 2px; opacity: 0.55; transition: opacity 120ms ease;
+}
+.link:hover, .link:focus-within { opacity: 1; }
+button { font: inherit; color: inherit; background: none; border: 0; cursor: pointer;
+  border-radius: 999px; display: inline-flex; align-items: center; gap: 5px; padding: 4px 8px; }
+button:hover { background: rgba(255,255,255,0.1); }
+button:focus-visible { outline: 2px solid rgba(255,207,51,0.6); }
+.close { padding: 4px; }
+svg { display: block; width: 12px; height: 12px; }
+.note { padding: 4px 8px 4px 4px; color: #ffcf33; font-weight: 500; }
+`;
+// Feather `edit-3` and `x`, inline: the player has no IconService.
+const EDIT_ICON = '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M12 20h9"/><path d="M16.5 3.5a2.121 2.121 0 0 1 3 3L7 19l-4 1 1-4L16.5 3.5z"/></svg>';
+const CLOSE_ICON = '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><line x1="18" y1="6" x2="6" y2="18"/><line x1="6" y1="6" x2="18" y2="18"/></svg>';
+const isHidden = () => {
+    try {
+        return sessionStorage.getItem(HIDDEN_KEY) === '1';
+    }
+    catch {
+        return false;
+    }
+};
+/** Mount the link; returns the teardown. Hidden for the rest of the tab's session by its close button. */
+export function mountEditorLink(editorUrl) {
+    if (isHidden())
+        return () => undefined;
+    const host = document.createElement('div');
+    host.className = 'pix3-editor-link';
+    const root = host.attachShadow({ mode: 'open' });
+    root.innerHTML = `<style>${STYLE}</style>
+<div class="link" part="link">
+  <button type="button" data-action="open" title="Open this project in the Pix3 editor">${EDIT_ICON}<span>Pix3 editor</span></button>
+  <span class="note" hidden>Already open in another tab</span>
+  <button type="button" class="close" data-action="hide" title="Hide" aria-label="Hide the editor link">${CLOSE_ICON}</button>
+</div>`;
+    const link = root.querySelector('.link');
+    const note = root.querySelector('.note');
+    // Keep the game's own listeners out of the link's clicks.
+    for (const type of ['pointerdown', 'pointerup', 'touchstart', 'touchend', 'keydown']) {
+        link.addEventListener(type, event => event.stopPropagation());
+    }
+    let noteTimer;
+    root.addEventListener('click', event => {
+        const action = event.target
+            ?.closest('[data-action]')
+            ?.getAttribute('data-action');
+        if (action === 'hide') {
+            try {
+                sessionStorage.setItem(HIDDEN_KEY, '1');
+            }
+            catch {
+                // Hidden for this page only.
+            }
+            host.remove();
+        }
+        else if (action === 'open') {
+            void openEditor(editorUrl).then(outcome => {
+                if (outcome !== 'already-open')
+                    return;
+                note.hidden = false;
+                clearTimeout(noteTimer);
+                noteTimer = setTimeout(() => (note.hidden = true), 3000);
+            });
+        }
+    });
+    document.body.appendChild(host);
+    return () => {
+        clearTimeout(noteTimer);
+        host.remove();
+    };
+}

package/dist/player/index.d.ts

@@ -8,6 +8,9 @@ import 'virtual:pix3/postprocessing';
  * `index.html` (zip). Port of the 1.x `runtime/src/main.ts` + `register-project-scripts.ts`.
  *
  * `window.__PIX3_PLAYER__` is the gate's witness: `status`, `frames` (loop iterations), `errors`.
+ * In dev (`virtual:pix3/dev`), `/?debug` adds the debug overlay (`player/debug/`) and
+ * `__PIX3_PLAYER__.debug.snapshot()`, a plain page gets the "Pix3 editor" link
+ * (`player/dev/`), and `?scene=<res path>` boots that scene.
  */
 export interface Pix3PlayerState {
     status: 'booting' | 'running' | 'failed';
@@ -17,6 +20,10 @@ export interface Pix3PlayerState {
     /** The scene the player booted into. */
     scene: string | null;
     runner: SceneRunner | null;
+    /** Debug mode only (`/?debug` in dev): the overlay's numbers, for an agent over CDP. */
+    debug?: {
+        snapshot(): unknown;
+    };
 }
 declare global {
     interface Window {

package/dist/player/index.js

@@ -1,4 +1,5 @@
 import { AssetLoader, AudioService, registerBuiltInScripts, registerProjectScriptExports, ResourceManager, RuntimeRenderer, SceneLoader, SceneManager, SceneRunner, ScriptRegistry, } from '@pix3/runtime';
+import { devSceneOverride, installDevTools } from 'virtual:pix3/dev';
 import { embeddedAssets } from 'virtual:pix3/embedded-assets';
 import { installNetworkService } from 'virtual:pix3/network';
 import { modules as projectScriptModules } from 'virtual:pix3/project-scripts';
@@ -30,6 +31,19 @@ const installState = () => {
     });
     return state;
 };
+/**
+ * Dev only: the `?scene=` the editor's Play in Browser Tab / with Profiler asks for, when it is one
+ * of the project's scenes (a prefab or a typo falls back to the entry scene, with a warning).
+ */
+const requestedScene = () => {
+    const scene = devSceneOverride();
+    if (!scene)
+        return null;
+    if (scenePaths.includes(scene))
+        return scene;
+    console.warn(`[pix3] ?scene=${scene} is not one of the project's scenes; starting the entry scene.`);
+    return null;
+};
 /** Boot the game into `target` (a selector or an element; `#app` by default). */
 export async function startGame(target = '#app', options = {}) {
     const state = installState();
@@ -49,7 +63,7 @@ export async function startGame(target = '#app', options = {}) {
         // No SceneSaver: a player never writes scenes back out, and one would pin every node class
         // and `yaml.stringify` into the bundle (CLAUDE.md «Playable export size»).
         const sceneManager = new SceneManager(sceneLoader);
-        const scenePath = options.scene || activeScenePath || scenePaths[0];
+        const scenePath = options.scene || requestedScene() || activeScenePath || scenePaths[0];
         if (!scenePath)
             throw new Error('No scenes found in this project.');
         state.scene = scenePath;
@@ -75,6 +89,9 @@ export async function startGame(target = '#app', options = {}) {
         // Multiplayer (D5): owned by the runner, inert until a script connects; the generated module
         // is a no-op when nothing in the project mentions the network.
         installNetworkService(runner);
+        // Debug mode (`/?debug`, dev only): the overlay subscribes before the scene loads, so a
+        // failed boot still shows its errors there.
+        installDevTools({ runner, renderer, audio: audioService, state });
         runner.setBatching2DEnabled(true);
         runner.setProjectFonts(runtimeFonts.length > 0 ? runtimeFonts : null);
         if (runtimeLocalization) {

package/dist/vite-config.js

@@ -19,8 +19,9 @@ export const pix3ViteConfig = (options) => {
     const { user, format } = options;
     const projectRoot = resolve(user.root ?? process.cwd());
     const linkedEditorCore = findPackageDir(projectRoot, '@pix3/editor-core');
-    // Vite checks `fs.allow` against real paths; a workspace or pnpm link points elsewhere.
-    const editorCoreDir = linkedEditorCore ? realpathSync(linkedEditorCore) : null;
+    // Vite checks `fs.allow` against real paths (`.native`: long names on Windows, as Vite resolves
+    // them); a workspace or pnpm link points elsewhere.
+    const editorCoreDir = linkedEditorCore ? realpathSync.native(linkedEditorCore) : null;
     // An explicit `fs.allow` switches off Vite's workspace-root default; keep it when the user
     // set none, and add this package (the page client and the player are served from it by
     // `/@fs/`) and the prebuilt editor (served from wherever npm put it: hoisted, pnpm, a
@@ -37,7 +38,9 @@ export const pix3ViteConfig = (options) => {
             // One runtime and one three for the game and the editor (plan §B.2, S1), plus the bare
             // subpaths the prebuilt editor imports (`dist/optimize-deps.json`).
             include: ['@pix3/runtime', 'three', ...editorOptimizeDeps(editorCoreDir)],
-            exclude: ['@pix3/editor-core'],
+            // The installed player imports virtual modules resolved by this plugin's Vite hooks;
+            // the dependency optimizer cannot resolve them while prebundling node_modules.
+            exclude: ['@pix3/editor-core', '@pix3/vite-plugin/player'],
         },
         server: { fs: { allow } },
         ...(format

package/package.json

@@ -1,60 +1,60 @@
-{
-  "name": "@pix3/vite-plugin",
-  "version": "2.0.0-alpha.0",
-  "description": "Pix3 editor, file API, sync barrier and build as a Vite plugin.",
-  "type": "module",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/pix3dev/pix3-core.git",
-    "directory": "packages/vite-plugin"
-  },
-  "homepage": "https://github.com/pix3dev/pix3-core/tree/main/packages/vite-plugin#readme",
-  "bugs": {
-    "url": "https://github.com/pix3dev/pix3-core/issues"
-  },
-  "engines": {
-    "node": ">=20.19"
-  },
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    },
-    "./player": {
-      "types": "./dist/player/index.d.ts",
-      "import": "./dist/player/index.js"
-    }
-  },
-  "files": [
-    "dist",
-    "README.md"
-  ],
-  "scripts": {
-    "build": "tsc -p tsconfig.build.json && tsc -p player/tsconfig.build.json",
-    "prepack": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && npm run build",
-    "type-check": "tsc --noEmit && tsc --noEmit -p tsconfig.build.json && tsc --noEmit -p player/tsconfig.json"
-  },
-  "dependencies": {
-    "fflate": "^0.8.3",
-    "vite-plugin-singlefile": "^2.3.3",
-    "ws": "^8.18.0",
-    "yaml": "^2.6.0"
-  },
-  "peerDependencies": {
-    "@pix3/runtime": "2.0.0-alpha.0",
-    "vite": "^7 || ^8"
-  },
-  "devDependencies": {
-    "@types/node": "^24.5.2",
-    "@types/ws": "^8.18.1",
-    "typescript": "~5.8.3",
-    "vite": "^8.3.3"
-  },
-  "license": "Apache-2.0",
-  "publishConfig": {
-    "access": "public",
-    "tag": "next"
-  }
-}
+{
+  "name": "@pix3/vite-plugin",
+  "version": "2.0.0-alpha.1",
+  "description": "Pix3 editor, file API, sync barrier and build as a Vite plugin.",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pix3dev/pix3-core.git",
+    "directory": "packages/vite-plugin"
+  },
+  "homepage": "https://github.com/pix3dev/pix3-core/tree/main/packages/vite-plugin#readme",
+  "bugs": {
+    "url": "https://github.com/pix3dev/pix3-core/issues"
+  },
+  "engines": {
+    "node": ">=20.19"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./player": {
+      "types": "./dist/player/index.d.ts",
+      "import": "./dist/player/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && tsc -p player/tsconfig.build.json",
+    "prepack": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && npm run build",
+    "type-check": "tsc --noEmit && tsc --noEmit -p tsconfig.build.json && tsc --noEmit -p player/tsconfig.json"
+  },
+  "dependencies": {
+    "fflate": "^0.8.3",
+    "vite-plugin-singlefile": "^2.3.3",
+    "ws": "^8.18.0",
+    "yaml": "^2.6.0"
+  },
+  "peerDependencies": {
+    "@pix3/runtime": "2.0.0-alpha.1",
+    "vite": "^7 || ^8"
+  },
+  "devDependencies": {
+    "@types/node": "^24.5.2",
+    "@types/ws": "^8.18.1",
+    "typescript": "~5.8.3",
+    "vite": "^8.3.3"
+  },
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public",
+    "tag": "next"
+  }
+}