@needle-tools/engine 5.1.0-alpha.8 → 5.1.0-beta

package/plugins/common/license.js

@@ -111,7 +111,7 @@ async function requestNeedleCloud(path, options) {
  * @param {DefaultOptions & {accessToken?:string, team:string|undefined}} opts
  */
 export async function replaceLicense(code, opts) {
-    const index = code?.indexOf("miOmwPp");
+    const index = code?.indexOf("$rJboqN");
     if (index >= 0) {
         const licenseResult = await resolveLicense(opts);
         if (!licenseResult) {
@@ -120,18 +120,18 @@ export async function replaceLicense(code, opts) {
         const end = code.indexOf(";", index);
         if (end >= 0) {
             const line = code.substring(index, end);
-            const replaced = "miOmwPp = \"" + licenseResult.type + "\"";
+            const replaced = "$rJboqN = \"" + licenseResult.type + "\"";
             code = code.replace(line, replaced);
         }
 
         // Also inject JWT if available
         if (licenseResult.jwt) {
-            const jwtIndex = code.indexOf("_$ALiqbpo");
+            const jwtIndex = code.indexOf("_$RRhFut");
             if (jwtIndex >= 0) {
                 const jwtEnd = code.indexOf(";", jwtIndex);
                 if (jwtEnd >= 0) {
                     const jwtLine = code.substring(jwtIndex, jwtEnd);
-                    const jwtReplaced = "_$ALiqbpo = \"" + licenseResult.jwt + "\"";
+                    const jwtReplaced = "_$RRhFut = \"" + licenseResult.jwt + "\"";
                     code = code.replace(jwtLine, jwtReplaced);
                 }
             }
@@ -318,11 +318,32 @@ function tryParseLicense(str, options = undefined) {
 }
 
 
+/** @type {Map<string, Promise<string | null>>} */
+const _publicIdentifierCache = new Map();
+
 /**
+ * Memoized public project identifier. Several plugins (defines, needle-app, next) request this per build,
+ * but it only needs to be resolved once - cache the promise by project_id to avoid redundant Needle Cloud
+ * requests. Keyed by project_id only; `opts` only controls logging and does not affect the result.
  * @param {string | undefined} project_id
  * @param {DefaultOptions | undefined} opts
+ * @returns {Promise<string | null>}
  */
 export async function getPublicIdentifier(project_id, opts = undefined) {
+    const key = project_id ?? "";
+    let cached = _publicIdentifierCache.get(key);
+    if (!cached) {
+        cached = getPublicIdentifierUncached(project_id, opts);
+        _publicIdentifierCache.set(key, cached);
+    }
+    return cached;
+}
+
+/**
+ * @param {string | undefined} project_id
+ * @param {DefaultOptions | undefined} opts
+ */
+async function getPublicIdentifierUncached(project_id, opts = undefined) {
 
     let accessToken = /** @type {string | undefined} */ (undefined);
     if (!accessToken) {

package/plugins/common/needle-engine.js

@@ -1,8 +1,11 @@
 
 
-// https://regex101.com/r/SVhzzD/1
+// Matches the `src` attribute of a <needle-engine> tag.
+// The value capture must accept any real src: relative paths (with dots, slashes, spaces),
+// full URLs, query strings, and the JSON-array form `["a.glb","b.glb"]`. It must also
+// tolerate other attributes appearing before or after `src`.
 // @ts-ignore
-const needleEngineRegex = /<needle-engine.*?src=["'](?<src>[\w\d]+?)["']>/gm;
+const needleEngineRegex = /<needle-engine\b[^>]*?\ssrc=(?<q>["'])(?<src>.*?)\k<q>/gms;
 
 
 /**

package/plugins/types/userconfig.d.ts

@@ -175,6 +175,28 @@ export type userSettings = {
      */
     openBrowser?: boolean;
 
+    /**
+     * Enable remote debugging: bind the dev server to your local network (`host`)
+     * and serve over HTTPS (via `@vitejs/plugin-basic-ssl`) so you can open the page
+     * on a phone, Quest or Apple Vision Pro on the same Wi‑Fi. The Needle logger
+     * already streams the device's console, errors and device info back over Vite's
+     * websocket (see `node_modules/.needle/logs/latest.client.needle.log`), so this
+     * makes "debug a scene on a real device from your laptop" work out of the box.
+     * HTTPS is required for WebXR / secure‑context features on the device; the
+     * self‑signed certificate shows a one‑time warning you accept on the device.
+     *
+     * Requires `@vitejs/plugin-basic-ssl` (for HTTPS) and, optionally,
+     * `qrcode-terminal` (to print a scannable QR code). Can also be toggled with the
+     * `NEEDLE_REMOTE` env var (`NEEDLE_REMOTE=1` / `=false`).
+     * - `true` — enable with a terminal QR code
+     * - `{ qr: false }` — enable but don't print the QR code
+     * @default false
+     */
+    remote?: boolean | {
+        /** Set to false to skip printing the scannable QR code. @default true */
+        qr?: boolean;
+    };
+
     disableLogging?: boolean;
 
     /** Set to true to disable the plugin that ensures VSCode workspace settings for custom-elements.json data */

package/plugins/vite/dts-generator.d.ts

@@ -1,3 +1,27 @@
+/**
+ * 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: unknown[], projectRoot: string, htmlDataPath: string, relativeFn?: (from: string, to: string) => string): string[] | null;
 /**
  * @param {"build" | "serve"} _command  Vite command (unused — runs in both modes)
  * @param {import('../types/needleConfig').needleMeta | null | undefined} _config

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("miOmwPp");
+                const index = src.indexOf("$rJboqN");
                 if (index >= 0) {
                     const end = src.indexOf(";", index);
                     if (end >= 0) {
                         const line = src.substring(index, end);
-                        const replaced = "miOmwPp = \"" + licenseResult.type + "\"";
+                        const replaced = "$rJboqN = \"" + 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("_$ALiqbpo");
+                    const jwtIndex = src.indexOf("_$RRhFut");
                     if (jwtIndex >= 0) {
                         const jwtEnd = src.indexOf(";", jwtIndex);
                         if (jwtEnd >= 0) {
                             const jwtLine = src.substring(jwtIndex, jwtEnd);
-                            const jwtReplaced = "_$ALiqbpo = \"" + licenseResult.jwt + "\"";
+                            const jwtReplaced = "_$RRhFut = \"" + 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 { bLW, __Carg, _$QyV } from "./engine_license.js";
+export { $fwGZrGe, _$qWUhYZU, _XtEQ } from "./engine_license.js";
 
 
 // ============================================================================