@needle-tools/engine 5.1.0-alpha.7 → 5.1.0-alpha.9

package/plugins/vite/dts-generator.js

@@ -16,7 +16,7 @@
  *   needleDtsGenerator(command, needleConfig, userSettings)
  */
 
-import { join, resolve, dirname } from 'path';
+import { join, resolve, dirname, relative } from 'path';
 import { existsSync, readFileSync, writeFileSync, mkdirSync, realpathSync } from 'fs';
 import { tryLoadProjectConfig } from './config.js';
 import { generateBindingsDts } from '../dts-generator/index.js';
@@ -35,6 +35,40 @@ try {
     // will silently skip generation rather than crashing the dev server.
 }
 
+/**
+ * Pure helper: compute the desired `html.customData` array for a project.
+ *
+ * Returns `null` when no change is required (the existing array already matches),
+ * otherwise the new array that should be written.
+ *
+ * The produced entry is a project-relative path with forward slashes. We use
+ * `path.relative` rather than a string replace because Vite normalises projectRoot
+ * to forward slashes while `htmlDataPath` carries the platform separator from
+ * `path.join` — a naive replace fails to match on Windows and leaves an absolute path.
+ * Any pre-existing entry pointing at a `needle-html-data.json` (e.g. an absolute path
+ * written by an older version of this plugin) is dropped so we don't accumulate
+ * duplicates or leave stale absolute paths behind.
+ *
+ * Exported for testing. The `relativeFn` seam lets tests reproduce platform-specific
+ * separator behaviour (`path.win32.relative` / `path.posix.relative`) deterministically.
+ *
+ * @param {unknown[]} existing  Current html.customData entries
+ * @param {string} projectRoot
+ * @param {string} htmlDataPath  Absolute path to the generated needle-html-data.json
+ * @param {(from: string, to: string) => string} [relativeFn]
+ * @returns {string[] | null}
+ */
+export function computeHtmlCustomData(existing, projectRoot, htmlDataPath, relativeFn = relative) {
+    const relPath = relativeFn(projectRoot, htmlDataPath).replace(/\\/g, "/");
+
+    const cleaned = /** @type {string[]} */ (existing.filter(entry =>
+        typeof entry !== "string" || !entry.replace(/\\/g, "/").endsWith("needle-html-data.json")));
+    const next = [...cleaned, relPath];
+
+    if (existing.length === next.length && existing.every((v, i) => v === next[i])) return null;
+    return next;
+}
+
 /**
  * Ensure `.vscode/settings.json` references the generated `needle-html-data.json`
  * so VS Code provides `data-bind-needle` completions in HTML files automatically.
@@ -48,9 +82,6 @@ function ensureVscodeHtmlCustomData(projectRoot, htmlDataPath) {
         const vscodeDir = join(projectRoot, ".vscode");
         const settingsPath = join(vscodeDir, "settings.json");
 
-        // Relative path from project root for portability
-        const relPath = htmlDataPath.replace(projectRoot + "/", "").replace(projectRoot + "\\", "");
-
         /** @type {Record<string, unknown>} */
         let settings = {};
         if (existsSync(settingsPath)) {
@@ -60,10 +91,12 @@ function ensureVscodeHtmlCustomData(projectRoot, htmlDataPath) {
         }
 
         const key = "html.customData";
-        const existing = Array.isArray(settings[key]) ? /** @type {string[]} */ (settings[key]) : [];
-        if (existing.includes(relPath)) return; // already registered
+        const existing = Array.isArray(settings[key]) ? /** @type {unknown[]} */ (settings[key]) : [];
+
+        const next = computeHtmlCustomData(existing, projectRoot, htmlDataPath);
+        if (next === null) return; // already up-to-date
 
-        settings[key] = [...existing, relPath];
+        settings[key] = next;
 
         mkdirSync(vscodeDir, { recursive: true });
         writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n", "utf8");

package/plugins/vite/index.d.ts

@@ -56,7 +56,9 @@ export { needleFacebookInstantGames } from "./facebook-instant-games.js";
 export { needleImportsLogger } from "./imports-logger.js";
 export { needleBuildInfo } from "./buildinfo.js";
 export { needleApp } from "./needle-app.js";
+export { needleLogger } from "./logger.js";
 export { needleServer } from "./server.js";
 export * from "./gzip.js";
 export * from "./config.js";
 export { needleMakeFilesLocal, needleLocalFilesSceneAnalysis } from "./local-files.js";
+export { needleRemote, isRemoteEnabled } from "./remote.js";

package/plugins/vite/index.js

@@ -82,6 +82,10 @@ import { needleServer } from "./server.js";
 import { needleNPM } from "./npm.js";
 import { needleTransformCode } from "./transform.js";
 import { needleLogger } from "./logger.js";
+export { needleLogger } from "./logger.js";
+import { needleRemote, isRemoteEnabled } from "./remote.js";
+export { needleRemote, isRemoteEnabled } from "./remote.js";
+import { needleLog } from "./logging.js";
 import { viteFixWorkerImport } from "../common/worker.js";
 
 export { needleServer } from "./server.js";
@@ -163,11 +167,24 @@ export async function needlePlugins(command = undefined, config = undefined, use
         needleServer(command, config, userSettings),
         needleNPM(command, config, userSettings),
         needleApp(command, config, userSettings),
+        needleRemote(command, config, userSettings),
         viteFixWorkerImport(),
         // IMPORTANT: needleBuildInfo should be the last plugin, since it waits for the build pipeline to finish and then collects information about the build output directory
         needleBuildInfo(command, config, userSettings),
     ];
 
+    // Remote debugging serves over HTTPS so WebXR / secure‑context features work on
+    // the device. HTTPS is provided by @vitejs/plugin-basic-ssl (a peer the user
+    // installs when they opt in); load it lazily so it's never required otherwise.
+    if (command !== "build" && isRemoteEnabled(userSettings)) {
+        try {
+            const { default: basicSsl } = await import("@vitejs/plugin-basic-ssl");
+            array.push(basicSsl());
+        } catch {
+            needleLog("needle-remote", "Remote HTTPS needs `@vitejs/plugin-basic-ssl` — install it: npm i -D @vitejs/plugin-basic-ssl", "warn");
+        }
+    }
+
     const asap = await needleAsap(command, config, userSettings);
     if(asap) array.push(asap);
 

package/plugins/vite/license.js

@@ -49,12 +49,12 @@ export function needleLicense(command, config, userSettings) {
                 let modified = false;
 
                 // Replace license type
-                const index = src.indexOf("__nNJ");
+                const index = src.indexOf("DUZpOVcM");
                 if (index >= 0) {
                     const end = src.indexOf(";", index);
                     if (end >= 0) {
                         const line = src.substring(index, end);
-                        const replaced = "__nNJ = \"" + licenseResult.type + "\"";
+                        const replaced = "DUZpOVcM = \"" + licenseResult.type + "\"";
                         src = src.replace(line, replaced);
                         modified = true;
                     }
@@ -62,12 +62,12 @@ export function needleLicense(command, config, userSettings) {
 
                 // Replace license JWT (same pattern)
                 if (licenseResult.jwt) {
-                    const jwtIndex = src.indexOf("_ldXlow");
+                    const jwtIndex = src.indexOf("__Bjqq");
                     if (jwtIndex >= 0) {
                         const jwtEnd = src.indexOf(";", jwtIndex);
                         if (jwtEnd >= 0) {
                             const jwtLine = src.substring(jwtIndex, jwtEnd);
-                            const jwtReplaced = "_ldXlow = \"" + licenseResult.jwt + "\"";
+                            const jwtReplaced = "__Bjqq = \"" + licenseResult.jwt + "\"";
                             src = src.replace(jwtLine, jwtReplaced);
                             modified = true;
                         }

package/plugins/vite/needle-app.js

@@ -1,6 +1,7 @@
 import { writeFile } from 'fs';
 import { tryParseNeedleEngineSrcAttributeFromHtml } from '../common/needle-engine.js';
 import { needleLog } from './logging.js';
+import { getPublicIdentifier } from '../common/license.js';
 
 
 
@@ -21,6 +22,22 @@ export function needleApp(command, config, userSettings) {
 
     let outputDir = "dist";
 
+    // The engine API is emitted as a dedicated, deterministically-named facade chunk so that the
+    // generated needle-app.js can re-export it - giving users a single import path (the same URL they
+    // load needle-app.js from also serves the engine API). See buildStart below.
+    // Emitted INTO assets/ (alongside the app's other chunks) on purpose: the app entry lives in assets/
+    // and then references the facade with a same-directory specifier ("./needle-app.engine.js"). A root-level
+    // facade would be referenced as "../needle-app.engine.js", and Vite computes preload-dependency hints with
+    // Node's path.relative, which returns backslashes on Windows for cross-directory paths ("..\\needle-app.engine.js")
+    // - a broken modulepreload URL. Keeping it in assets/ avoids the "../" entirely.
+    const apiFacadeFileName = "assets/needle-app.engine.js";
+    let apiFacadeEmitted = false;
+
+    // Public project identifier, baked as a comment into the generated needle-app.js for traceability.
+    // This is the Needle Cloud `public_key` (the same value injected into client code as NEEDLE_PUBLIC_KEY) -
+    // it is PUBLIC and safe to embed. It is NOT the secret NEEDLE_CLOUD_TOKEN. Null when no token is configured.
+    let publicKey = null;
+
     /**
      * @type {import('vite').Plugin}
      */
@@ -28,6 +45,35 @@ export function needleApp(command, config, userSettings) {
         {
             name: 'needle:app',
             enforce: "post",
+            async buildStart() {
+                // Emit @needle-tools/engine/needle-app (a thin re-export of the public API) as its own
+                // entry chunk with a fixed filename. Built in the same pass as the app, it deduplicates
+                // into the same engine chunks - so importing hooks from it drives the SAME running scene.
+                try {
+                    const resolved = await this.resolve('@needle-tools/engine/needle-app');
+                    if (resolved?.id) {
+                        this.emitFile({
+                            type: 'chunk',
+                            id: resolved.id,
+                            fileName: apiFacadeFileName,
+                            // Preserve the full re-exported API surface. Without this, the build tree-shakes the
+                            // facade down to only the single export the app internally consumes, so a page-side
+                            // `import { onStart } from ".../needle-app.js"` fails with "does not provide an export".
+                            preserveSignature: 'allow-extension',
+                        });
+                        apiFacadeEmitted = true;
+                    }
+                    else {
+                        needleLog("needle-app", "Could not resolve @needle-tools/engine/needle-app - engine hooks (onStart etc.) will not be importable from needle-app.js", "warn", { dimBody: false });
+                    }
+                }
+                catch (e) {
+                    needleLog("needle-app", "Failed to emit " + apiFacadeFileName + " facade: " + e.message, "warn", { dimBody: false });
+                }
+
+                // Fetch the public project identifier (best-effort; null without a NEEDLE_CLOUD_TOKEN).
+                publicKey = await getPublicIdentifier(undefined).catch(() => null);
+            },
             configResolved(config) {
                 outputDir = config.build.outDir || "dist";
             },
@@ -52,7 +98,7 @@ export function needleApp(command, config, userSettings) {
 
                                 const main_asset = attribute_src?.[0] || imported_glbs?.[0];
 
-                                const webComponent = generateNeedleEmbedWebComponent(path, main_asset);
+                                const webComponent = generateNeedleEmbedWebComponent(path, main_asset, apiFacadeEmitted ? apiFacadeFileName : null, publicKey);
                                 await writeFile(`${outputDir}/needle-app.js`, webComponent, (err) => {
                                     if (err) {
                                         needleLog("needle-app", "Could not create needle-app.js: " + err.message, "error", { dimBody: false });
@@ -78,9 +124,11 @@ export function needleApp(command, config, userSettings) {
 /**
  * @param {string} filepath
  * @param {string | null} src
+ * @param {string | null | undefined} apiFacadeFile Filename of the emitted engine-API facade chunk (e.g. "needle-app.engine.js"). When set, its API is re-exported so engine hooks can be imported from needle-app.js.
+ * @param {string | null | undefined} publicKey Public Needle Cloud project identifier, baked into the file header as a comment for traceability.
  * @returns {string}
  */
-function generateNeedleEmbedWebComponent(filepath, src) {
+function generateNeedleEmbedWebComponent(filepath, src, apiFacadeFile, publicKey) {
 
 
     // filepath is e.g. `assets/index-XXXXXXXX.js`
@@ -89,8 +137,27 @@ function generateNeedleEmbedWebComponent(filepath, src) {
 
     const componentDefaultName = 'needle-app';
 
-    return `
+    // Bake the asset path in as a safely-escaped string literal: paths can contain quotes/spaces/backticks,
+    // and JSON string literals are valid JS string literals. No asset → serializes to the literal `null`,
+    // matching the previous default. Actual origin resolution happens at runtime via `new URL(...)` below.
+    const defaultSrc = JSON.stringify(src ?? null);
+
+    // Re-export the engine API facade so users have a SINGLE import path: the same URL they load
+    // needle-app.js from also serves the engine hooks (`import { onStart } from "<deploy>/needle-app.js"`).
+    // The facade is a separate, deterministically-named chunk that shares the app's engine instance,
+    // so the re-export resolves to the live scene. Specifier is relative to this file's own URL.
+    const apiReexport = apiFacadeFile
+        ? `export * from ${JSON.stringify("./" + apiFacadeFile)};\n`
+        : ``;
 
+    // File header for traceability: which build produced this file, and (if available) the public project id.
+    // Values are sanitized to a single line so they cannot break out of the `//` comment.
+    const oneLine = (/** @type {string} */ v) => String(v).replace(/[\r\n]+/g, " ").trim();
+    let header = `// needle-app.js - generated by the @needle-tools/engine needle-app plugin\n`;
+    header += `// build time: ${oneLine(new Date().toISOString())}\n`;
+    if (publicKey) header += `// public key: ${oneLine(publicKey)}\n`;
+
+    return `${header}${apiReexport}
 // Needle Engine attributes we want to allow to be overriden
 const knownAttributes = [
     "src",
@@ -170,8 +237,14 @@ if (!customElements.get(componentName)) {
         updateAttributes() {
             console.debug("NeedleApp updating attributes");
             
-            const src = this.getAttribute('src') || ${src?.length ? `\`\${this.basePath}/${src}\`` : null};
-            if(src) this.needleEngine.setAttribute("src", src);
+            let src = this.getAttribute('src') || ${defaultSrc};
+            if(src) {
+                // Resolve the asset URL against this script's own origin (import.meta.url) so relative
+                // paths keep resolving to the deployed app even when <needle-app> is embedded on a
+                // different domain (e.g. Webflow). Absolute URLs pass through unchanged; spaces get encoded.
+                src = new URL(src, this.basePath + '/').href;
+                this.needleEngine.setAttribute("src", src);
+            }
             else this.needleEngine.removeAttribute("src");
 
             for(const attr of knownAttributes) {

package/plugins/vite/remote.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Whether remote debugging is enabled. Toggled by the `remote` user setting or the
+ * `NEEDLE_REMOTE` env var (the env var wins so you can flip it without editing the
+ * config: `NEEDLE_REMOTE=1 npm run dev`, or `NEEDLE_REMOTE=false` to force off).
+ * @param {import('../types/userconfig.js').userSettings} [userSettings]
+ * @returns {boolean}
+ */
+export function isRemoteEnabled(userSettings?: import("../types/userconfig.js").userSettings): boolean;
+/**
+ * Remote debugging plugin.
+ *
+ * Binds the Vite dev server to the LAN (`server.host = true`) so other devices can
+ * reach it, and prints the network URL + a scannable QR code once the server is
+ * listening. HTTPS itself is provided by `@vitejs/plugin-basic-ssl`, which
+ * {@link needlePlugins} adds to the plugin array when remote is enabled (WebXR and
+ * other secure‑context features on the device require https).
+ *
+ * The page's console / errors / device info already stream back to the dev server
+ * via the Needle logger (`needleLogger` + `logger.client.js`) over Vite's
+ * websocket, landing in `node_modules/.needle/logs/latest.client.needle.log`. This
+ * plugin is read‑only: it does not (yet) inject commands back into the page.
+ *
+ * @param {"build" | "serve" | undefined} command
+ * @param {unknown} _config
+ * @param {import('../types/userconfig.js').userSettings} [userSettings]
+ * @returns {import('vite').Plugin | null}
+ */
+export function needleRemote(command: "build" | "serve" | undefined, _config: unknown, userSettings?: import("../types/userconfig.js").userSettings): import("vite").Plugin | null;

package/plugins/vite/remote.js

@@ -0,0 +1,124 @@
+// @ts-check
+import os from "os";
+import { needleLog } from "./logging.js";
+
+/**
+ * Whether remote debugging is enabled. Toggled by the `remote` user setting or the
+ * `NEEDLE_REMOTE` env var (the env var wins so you can flip it without editing the
+ * config: `NEEDLE_REMOTE=1 npm run dev`, or `NEEDLE_REMOTE=false` to force off).
+ * @param {import('../types/userconfig.js').userSettings} [userSettings]
+ * @returns {boolean}
+ */
+export function isRemoteEnabled(userSettings) {
+    const env = process.env.NEEDLE_REMOTE;
+    if (env !== undefined && env !== "") {
+        const v = env.toLowerCase();
+        return !(v === "false" || v === "0" || v === "off" || v === "no");
+    }
+    const r = userSettings?.remote;
+    return r === true || (typeof r === "object" && r !== null);
+}
+
+/**
+ * Pick the first non-internal IPv4 LAN address — the one a phone / headset on the
+ * same Wi‑Fi can reach. Prefers the common private ranges and otherwise falls back
+ * to the first external IPv4 found.
+ * @returns {string | null}
+ */
+function lanAddress() {
+    const ifaces = os.networkInterfaces();
+    /** @type {string | null} */
+    let fallback = null;
+    for (const name of Object.keys(ifaces)) {
+        for (const net of ifaces[name] || []) {
+            // Node reports family as the string "IPv4" (older versions: the number 4)
+            if (net.family !== "IPv4" && /** @type {unknown} */ (net.family) !== 4) continue;
+            if (net.internal) continue;
+            if (/^(10\.|192\.168\.|172\.(1[6-9]|2\d|3[01])\.)/.test(net.address)) return net.address;
+            if (!fallback) fallback = net.address;
+        }
+    }
+    return fallback;
+}
+
+/**
+ * Remote debugging plugin.
+ *
+ * Binds the Vite dev server to the LAN (`server.host = true`) so other devices can
+ * reach it, and prints the network URL + a scannable QR code once the server is
+ * listening. HTTPS itself is provided by `@vitejs/plugin-basic-ssl`, which
+ * {@link needlePlugins} adds to the plugin array when remote is enabled (WebXR and
+ * other secure‑context features on the device require https).
+ *
+ * The page's console / errors / device info already stream back to the dev server
+ * via the Needle logger (`needleLogger` + `logger.client.js`) over Vite's
+ * websocket, landing in `node_modules/.needle/logs/latest.client.needle.log`. This
+ * plugin is read‑only: it does not (yet) inject commands back into the page.
+ *
+ * @param {"build" | "serve" | undefined} command
+ * @param {unknown} _config
+ * @param {import('../types/userconfig.js').userSettings} [userSettings]
+ * @returns {import('vite').Plugin | null}
+ */
+export function needleRemote(command, _config, userSettings) {
+    if (command === "build") return null;
+    if (!isRemoteEnabled(userSettings)) return null;
+
+    const r = userSettings?.remote;
+    const showQr = !(typeof r === "object" && r !== null && r.qr === false);
+    let announced = false;
+
+    return {
+        name: "needle:remote",
+        enforce: "pre",
+        config(config) {
+            if (!config.server) config.server = {};
+            // Bind 0.0.0.0 so phones / headsets on the same network can connect.
+            // Respect an explicit host the user already set.
+            if (config.server.host === undefined) config.server.host = true;
+        },
+        configureServer(server) {
+            const announce = async () => {
+                if (announced) return;
+                const addr = server.httpServer?.address?.();
+                const port = (addr && typeof addr === "object" && addr.port) || server.config.server.port;
+                const ip = lanAddress();
+                if (!port || !ip) {
+                    needleLog("needle-remote", "Remote debugging is ON but no LAN address was found — is this machine on a network?", "warn");
+                    return;
+                }
+                announced = true;
+                const protocol = server.config.server.https ? "https" : "http";
+                const url = `${protocol}://${ip}:${port}/`;
+                const note = protocol === "https"
+                    ? "\n  (accept the one‑time self‑signed certificate warning on the device)"
+                    : "\n  (no HTTPS — install @vitejs/plugin-basic-ssl for WebXR / secure‑context features)";
+                needleLog("needle-remote", `Remote debugging is ON — open on a device on the same Wi‑Fi:\n  ${url}${note}`);
+                // The device's console / errors stream back over Vite's HMR websocket
+                // (via the Needle logger). With HMR disabled there's no socket, so the
+                // logs would silently never arrive — warn rather than leave you guessing.
+                if (server.config.server.hmr === false) {
+                    needleLog("needle-remote", "HMR is disabled, so device console logs won't stream back (they ride the HMR websocket). Enable HMR to capture remote logs.", "warn");
+                }
+                if (showQr) await printQr(url);
+            };
+            // `listening` fires once the port is bound; resolve the real port from it.
+            server.httpServer?.once("listening", announce);
+        },
+    };
+}
+
+/**
+ * Print a scannable QR code of the URL to the terminal (best effort — needs the
+ * optional `qrcode-terminal` package; if it's missing we just say how to get it).
+ * @param {string} url
+ */
+async function printQr(url) {
+    try {
+        const mod = await import("qrcode-terminal");
+        const qrcode = /** @type {{ generate: (text: string, opts?: object) => void }} */ (mod.default || mod);
+        qrcode.generate(url, { small: true });
+    } catch {
+        needleLog("needle-remote", "Install `qrcode-terminal` to show a scannable QR code here: npm i -D qrcode-terminal", "log");
+    }
+}

package/src/engine/api.ts

@@ -230,7 +230,7 @@ export * from "./engine_input.js";
 export { InstancingUtil } from "./engine_instancing.js";
 
 /** License checking utilities */
-export { _IrDl, _LMtzpq, $HDGDr } from "./engine_license.js";
+export { _imGyfK, _QchMjAD, rkHTARX } from "./engine_license.js";
 
 
 // ============================================================================

package/src/engine/engine_audio.ts

@@ -1,25 +1,78 @@
 import { AudioContext } from "three";
 
 import { Application } from "./engine_application.js";
+import { getParam } from "./engine_utils.js";
 
-/** 
- * @internal 
- * Ensure the audio context is resumed if it gets suspended or interrupted */
+/** Verbose audio logging, opt-in via `?debugaudio` (same flag AudioSource uses). */
+const debug = getParam("debugaudio");
+
+/**
+ * iOS Safari exposes a non-standard `"interrupted"` state in addition to the
+ * spec'd `AudioContextState`s when the audio session is taken away (e.g. the
+ * device is locked or another app starts playing audio).
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/BaseAudioContext/state#resuming_interrupted_play_states_in_ios_safari
+ */
+export type InterruptibleAudioContextState = AudioContextState | "interrupted";
+
+/**
+ * @internal
+ * Pure policy deciding whether `AudioContext.resume()` should be attempted right now.
+ *
+ * The context needs resuming when it is `"suspended"` or (on iOS) `"interrupted"`.
+ * But resuming is only allowed while the document is **visible**: on iOS Safari,
+ * calling `resume()` while the page is backgrounded or the device is locked fails
+ * with `InvalidStateError: Failed to start the audio device`, because the audio
+ * hardware cannot be started in the background. In that case the resume must be
+ * deferred until the page becomes visible again.
+ *
+ * @param state The current (possibly iOS-interrupted) audio context state.
+ * @param visibility The current `document.visibilityState`.
+ * @returns `true` if `resume()` should be called now, `false` if it should be deferred.
+ */
+export function shouldResumeAudioContext(
+    state: InterruptibleAudioContextState,
+    visibility: DocumentVisibilityState,
+): boolean {
+    // Resuming while hidden throws InvalidStateError on iOS — defer until visible.
+    if (visibility !== "visible") return false;
+    return state === "suspended" || state === "interrupted";
+}
+
+/** Resume the shared AudioContext if it is suspended/interrupted and the page is visible. */
+function recoverAudioContext() {
+    const ctx = AudioContext.getContext();
+    const state = ctx.state as InterruptibleAudioContextState;
+    const visibility = typeof document !== "undefined" ? document.visibilityState : "visible";
+    if (!shouldResumeAudioContext(state, visibility)) return;
+    ctx.resume()
+        .then(() => { if (debug) console.log("AudioContext resumed successfully"); })
+        .catch(e => { if (debug) console.warn("Failed to resume AudioContext: " + e); });
+}
+
+/**
+ * @internal
+ * Keep the shared AudioContext alive across suspends/interruptions (tab switch, device lock, audio
+ * session interruption). On returning to the foreground we simply resume() the EXISTING context —
+ * the same approach three.js uses, which recovers cleanly because AudioSource plays clips through a
+ * MediaElementAudioSourceNode (an <audio> element), whose media session iOS keeps alive across a
+ * lock. We deliberately do NOT close/recreate the context: on-device testing showed that makes iOS
+ * worse (a recreated context's output stays dead) and it is unnecessary.
+ */
 export function ensureAudioContextIsResumed() {
     Application.registerWaitForInteraction(() => {
-        // this is a fix for https://github.com/mrdoob/three.js/issues/27779 & https://linear.app/needle/issue/NE-4257
+        // https://github.com/mrdoob/three.js/issues/27779 & https://linear.app/needle/issue/NE-4257
         const ctx = AudioContext.getContext();
-        ctx.addEventListener("statechange", () => {
-            setTimeout(() => {
-                // on iOS the audiocontext can be interrupted: https://developer.mozilla.org/en-US/docs/Web/API/BaseAudioContext/state#resuming_interrupted_play_states_in_ios_safari
-                const state = ctx.state as AudioContextState | "interrupted";
-                if (state === "suspended" || state === "interrupted") {
-                    ctx.resume()
-                        .then(() => { console.log("AudioContext resumed successfully"); })
-                        .catch((e) => { console.log("Failed to resume AudioContext: " + e); });
-                }
-            }, 500);
-        });
+        ctx.addEventListener("statechange", () => setTimeout(recoverAudioContext, 300));
+
+        // iOS frequently rejects the first resume() right after foregrounding with InvalidStateError,
+        // then accepts one a few hundred ms later with no follow-up statechange — so retry with a
+        // short backoff. Each attempt is a no-op once running.
+        if (typeof document !== "undefined") {
+            document.addEventListener("visibilitychange", () => {
+                if (document.visibilityState !== "visible") return;
+                for (const delay of [0, 250, 600, 1200, 2000]) setTimeout(recoverAudioContext, delay);
+            });
+        }
     });
 }
 

package/src/engine/engine_init.ts

@@ -8,7 +8,7 @@ import { initBuiltinTypes } from "./codegen/register_types.js";
 import { initSpatialConsole } from "./debug/debug_spatial_console.js";
 import { initAddressableSerializers } from "./engine_addressables.js";
 import { ensureAudioContextIsResumed } from "./engine_audio.js";
-import { _$zdhiyteo } from "./engine_license.js";
+import { _NHJZozV } from "./engine_license.js";
 import { initNeedleLoader } from "./engine_loaders.js";
 import { initPhysics } from "./engine_physics_rapier.js";
 import { initBuiltinSerializers } from "./engine_serialization_builtin_serializer.js";
@@ -59,7 +59,7 @@ export function initEngine() {
     initPhysics();
     initXR();
     initSpatialConsole();
-    _$zdhiyteo();
+    _NHJZozV();
 
     // Must be last. customElements.define() upgrades existing <needle-engine>
     // elements synchronously, which can trigger context.create() and dispatch

package/src/engine/engine_instantiate_resolve.ts

@@ -137,19 +137,39 @@ export function resolveInstanceReferences(objectMap: InstantiateReferenceMap): v
     }
 }
 
+/**
+ * Per-call traversal counters. Only populated when `?debuginstantiate` is set; null otherwise so
+ * the hot path stays allocation-free. Safe as module state because resolution runs synchronously
+ * and these calls never nest.
+ */
+type ResolveStats = { objects: number; components: number; props: number; remapped: number };
+let _resolveStats: ResolveStats | null = null;
+
 /**
  * Resolves string-based guid references in all components of a hierarchy using a GuidsMap.
  * Used by the glTF loading path where objects get new guids assigned and string references
  * (e.g. PlayableDirector track.outputs) need to be updated.
  */
 export function resolveStringGuidsInHierarchy(root: Object3D, guidsMap: GuidsMap): void {
+    if (!debug) {
+        resolveStringGuidsRecursive(root, guidsMap);
+        return;
+    }
+    _resolveStats = { objects: 0, components: 0, props: 0, remapped: 0 };
+    const start = (typeof performance !== "undefined" ? performance.now() : Date.now());
     resolveStringGuidsRecursive(root, guidsMap);
+    const ms = (typeof performance !== "undefined" ? performance.now() : Date.now()) - start;
+    const s = _resolveStats;
+    _resolveStats = null;
+    console.log(`[resolveStringGuids] root="${root.name}" objects=${s.objects} components=${s.components} propsVisited=${s.props} remapped=${s.remapped} mapSize=${Object.keys(guidsMap).length} in ${ms.toFixed(2)}ms`);
 }
 
 function resolveStringGuidsRecursive(obj: Object3D, guidsMap: GuidsMap): void {
+    if (_resolveStats) _resolveStats.objects++;
     if (obj.userData?.components) {
         for (const component of obj.userData.components) {
             if (component === null) continue;
+            if (_resolveStats) _resolveStats.components++;
             resolveStringGuidsInObject(component, guidsMap);
         }
     }
@@ -166,26 +186,33 @@ function resolveStringGuidsInObject(obj: any, guidsMap: GuidsMap, visited?: Weak
     visited.add(obj);
 
     for (const key of Object.keys(obj)) {
+        if (_resolveStats) _resolveStats.props++;
         const value = obj[key];
         if (value === null || value === undefined) continue;
         if (typeof value === "string") {
-            if (guidsMap[value]) {
-                obj[key] = guidsMap[value];
-            }
+            const mapped = guidsMap[value];
+            if (mapped) { obj[key] = mapped; if (_resolveStats) _resolveStats.remapped++; }
         }
         else if (Array.isArray(value)) {
             for (let i = 0; i < value.length; i++) {
-                if (typeof value[i] === "string" && guidsMap[value[i]]) {
-                    value[i] = guidsMap[value[i]];
+                const entry = value[i];
+                if (typeof entry === "string") {
+                    const mapped = guidsMap[entry];
+                    if (mapped) { value[i] = mapped; if (_resolveStats) _resolveStats.remapped++; }
                 }
-                else if (typeof value[i] === "object" && value[i] !== null) {
-                    resolveStringGuidsInObject(value[i], guidsMap, visited);
+                // Only descend into plain data (arrays and plain objects). See isPlainObject note below.
+                else if (Array.isArray(entry) || isPlainObject(entry)) {
+                    resolveStringGuidsInObject(entry, guidsMap, visited);
                 }
             }
         }
-        else if (typeof value === "object") {
-            // Skip known non-data objects
-            if (value.isObject3D || value.isComponent) continue;
+        // Only descend into plain objects. String guids only ever live in serialized plain-object
+        // data (e.g. PlayableDirector track.outputs). We must NOT traverse class instances —
+        // Object3D, Component, three.js value/render types (Material, Texture, BufferGeometry) or
+        // TypedArrays. Descending into the scene graph or geometry buffers (e.g. Object.keys on a
+        // multi-million-element Float32Array) makes hierarchy guid resolution scale with mesh data
+        // and dominates load time.
+        else if (isPlainObject(value)) {
             resolveStringGuidsInObject(value, guidsMap, visited);
         }
     }