@needle-tools/engine 6.0.0-alpha.6 → 6.0.0-alpha.7

package/src/engine/engine_license.ts

@@ -42,19 +42,19 @@ function setLicenseTimeout(ctx: IContext, callback: () => void, delay: number) {
     return timer;
 }
 
-const _$hziI: ((result: boolean) => void)[] = [];
+const $bvy: ((result: boolean) => void)[] = [];
 
 // DO NOT EDIT MANUALLY
-let __deG: string = "";
+let yBXL: string = "";
 // eslint-disable-next-line prefer-const
-let yDKPfo: string = "";
+let VkS: string = "";
 
 if (debug) {
-    console.log("License Type: " + __deG);
-    if (yDKPfo) {
-        console.log("License JWT: " + yDKPfo);
+    console.log("License Type: " + yBXL);
+    if (VkS) {
+        console.log("License JWT: " + VkS);
         try {
-            const payload = JSON.parse(atob(yDKPfo.split(".")[1].replace(/-/g, '+').replace(/_/g, '/')));
+            const payload = JSON.parse(atob(VkS.split(".")[1].replace(/-/g, '+').replace(/_/g, '/')));
             console.log("License JWT payload:", payload);
         }
         catch { console.log("License JWT payload: (failed to decode)"); }
@@ -65,8 +65,8 @@ if (debug) {
 }
 
 /** @internal */
-export function $jVksoCHS() {
-    switch (__deG) {
+export function __mor() {
+    switch (yBXL) {
         case "pro":
         case "enterprise":
             return true;
@@ -75,8 +75,8 @@ export function $jVksoCHS() {
 }
 
 /** @internal */
-export function _$sHuA() {
-    switch (__deG) {
+export function $TiDhB() {
+    switch (yBXL) {
         case "indie":
             return true;
     }
@@ -84,8 +84,8 @@ export function _$sHuA() {
 }
 
 /** @internal */
-export function $BZiUJx() {
-    switch (__deG) {
+export function __cshwS() {
+    switch (yBXL) {
         case "edu":
             return true;
     }
@@ -93,26 +93,26 @@ export function $BZiUJx() {
 }
 
 /** @internal */
-export function KLnyx() {
-    return $jVksoCHS() || _$sHuA() || $BZiUJx();
+export function _yActo() {
+    return __mor() || $TiDhB() || __cshwS();
 }
 
 
 /** @internal */
-export function _$jODX(cb: (result: boolean) => void) {
-    if ($jVksoCHS() || _$sHuA() || $BZiUJx()) {
+export function _PvsqpIB(cb: (result: boolean) => void) {
+    if (__mor() || $TiDhB() || __cshwS()) {
         cb(true);
         return () => {};
     }
-    _$hziI.push(cb);
+    $bvy.push(cb);
     return () => {
-        const index = _$hziI.indexOf(cb);
-        if (index >= 0) _$hziI.splice(index, 1);
+        const index = $bvy.indexOf(cb);
+        if (index >= 0) $bvy.splice(index, 1);
     };
 }
 
-function __QVQhCm(result: boolean) {
-    for (const cb of _$hziI) {
+function GuxGgwYi(result: boolean) {
+    for (const cb of $bvy) {
         try {
             cb(result);
         }
@@ -127,7 +127,7 @@ function __QVQhCm(result: boolean) {
 
 // ECDSA P-256 public key for verifying license JWTs (verification-only, safe to ship)
 /* eslint-disable no-secrets/no-secrets -- public key, not a secret */
-const _UHT = {
+const $xvChBB = {
     kty: "EC",
     crv: "P-256",
     x: "A34nyKMjhQYVgzeE4tyLUYdx34TAKogDa7v7PRaO9Lg",
@@ -151,7 +151,7 @@ function base64urlDecode(str: string): Uint8Array {
  * Verify a JWT license token and return the `type` claim if valid.
  * Returns null if the JWT is missing, malformed, or has an invalid signature.
  */
-async function _$IUNmiHVF(jwt: string): Promise<string | null> {
+async function _yCe(jwt: string): Promise<string | null> {
     if (!jwt) return null;
     try {
         const parts = jwt.split(".");
@@ -161,7 +161,7 @@ async function _$IUNmiHVF(jwt: string): Promise<string | null> {
 
         const key = await crypto.subtle.importKey(
             "jwk",
-            _UHT,
+            $xvChBB,
             { name: "ECDSA", namedCurve: "P-256" },
             false,
             ["verify"]
@@ -221,16 +221,16 @@ async function _$IUNmiHVF(jwt: string): Promise<string | null> {
 }
 
 /** Verify the injected JWT and update the license type if valid.
- * The engine ONLY trusts the JWT — the plain __deG string is ignored. */
+ * The engine ONLY trusts the JWT — the plain yBXL string is ignored. */
 let _jwtVerificationPromise: Promise<void> | undefined = undefined;
-async function wJwFeUbX(): Promise<void> {
+async function uztEyYP(): Promise<void> {
     // The bundled JWT may be empty when a build supplies a signed license file.
     // Do not return early: the meta tag below may provide the JWT instead.
     // Keep the bundled binding mutable so Vite's esbuild pre-bundling does not
     // treat its initial empty value as constant and remove JWT verification.
-    let jwt = yDKPfo;
+    let jwt = VkS;
     // Clear the bundled JWT after reading it; this assignment keeps the binding mutable.
-    yDKPfo = "";
+    VkS = "";
     if (!jwt && typeof document !== "undefined") {
         const licenseFile = document.querySelector('meta[name="needle-license"]')?.getAttribute("content");
         if (licenseFile) {
@@ -247,14 +247,14 @@ async function wJwFeUbX(): Promise<void> {
             }
         }
     }
-    const verifiedType = await _$IUNmiHVF(jwt);
+    const verifiedType = await _yCe(jwt);
     if (verifiedType) {
-        __deG = verifiedType;
+        yBXL = verifiedType;
         if (debug) console.log("License type set from verified JWT: " + verifiedType);
-        __QVQhCm(KLnyx());
+        GuxGgwYi(_yActo());
     }
     else {
-        __deG = "basic";
+        yBXL = "basic";
         if (debug && jwt) console.warn("JWT verification failed — license reset to basic");
     }
 }
@@ -377,7 +377,7 @@ export namespace Telemetry {
         // NOTE: this does NOT affect license enforcement — the /check call, the "forbidden"
         // overlay and the watermark/logo run on separate, ungated code paths.
         const attribute = domElement?.getAttribute("no-telemetry");
-        if ($jVksoCHS() && (attribute === "" || attribute === "true" || attribute === "1")) {
+        if (__mor() && (attribute === "" || attribute === "true" || attribute === "1")) {
             if (debug) console.debug("Telemetry is disabled via no-telemetry attribute");
             return false;
         }
@@ -705,21 +705,21 @@ export namespace Telemetry {
 }
 
 
-export function $bqSkkSKJ() {
+export function _htxWDE() {
 
-    if(__deG === "") __deG = "basic";
+    if(yBXL === "") yBXL = "basic";
 
     // Start JWT verification — must be here (not top-level) to avoid tree-shaking
-    _jwtVerificationPromise = wJwFeUbX();
+    _jwtVerificationPromise = uztEyYP();
     // Start after setting the initial type. At module scope the type was still "",
     // so Basic builds skipped the runtime check entirely.
-    _$cThps = __zwPG();
+    eNaXOZj = __mTgB();
 
     Telemetry.init();
     ContextRegistry.registerCallback(ContextEvent.ContextRegistered, evt => {
-        pTWobY(evt.context);
-        _$XfWxk(evt.context);
-        setLicenseTimeout(evt.context, () => _YuMDhu(evt.context), 2000);
+        __vTpQGDw(evt.context);
+        _$ygon(evt.context);
+        setLicenseTimeout(evt.context, () => NNhYdA(evt.context), 2000);
     });
     // ContextCreated fires after the renderer exists, so the canvas is available for context-loss monitoring
     ContextRegistry.registerCallback(ContextEvent.ContextCreated, evt => {
@@ -728,17 +728,17 @@ export function $bqSkkSKJ() {
     });
 }
 
-export let _$cThps: Promise<void> | undefined = undefined;
+export let eNaXOZj: Promise<void> | undefined = undefined;
 let applicationIsForbidden = false;
 let applicationForbiddenText = "";
-async function __zwPG() {
+async function __mTgB() {
     // Only perform the runtime license check once
-    if (_$cThps) return _$cThps;
+    if (eNaXOZj) return eNaXOZj;
     // Wait for JWT verification to complete first (if running)
     if (_jwtVerificationPromise) {
         await _jwtVerificationPromise;
     }
-    if (__deG === "basic") {
+    if (yBXL === "basic") {
         try {
             const licenseUrl = "https://needle.tools/api/v1/needle-engine/check?location=" + encodeURIComponent(window.location.href) + "&version=" + VERSION + "&generator=" + encodeURIComponent(GENERATOR);
             const res = await fetch(licenseUrl, {
@@ -750,27 +750,27 @@ async function __zwPG() {
             if (res?.status === 200) {
                 applicationIsForbidden = false;
                 if (debug) console.log("License check succeeded");
-                __deG = "pro";
-                __QVQhCm(true);
+                yBXL = "pro";
+                GuxGgwYi(true);
             }
             else if (res?.status === 403) {
-                __QVQhCm(false);
+                GuxGgwYi(false);
                 applicationIsForbidden = true;
                 applicationForbiddenText = await res.text();
             }
             else {
-                __QVQhCm(false);
+                GuxGgwYi(false);
                 if (debug) console.log("License check failed with status " + res?.status);
             }
         }
         catch (err) {
-            __QVQhCm(false);
+            GuxGgwYi(false);
             if (debug) console.error("License check failed", err);
         }
     }
-    else if (debug) console.log("Runtime license check is skipped because license is already applied as \"" + __deG + "\"");
+    else if (debug) console.log("Runtime license check is skipped because license is already applied as \"" + yBXL + "\"");
 }
-async function _$XfWxk(ctx: IContext) {
+async function _$ygon(ctx: IContext) {
     function createForbiddenElement() {
         const div = document.createElement("div");
         div.className = "needle-forbidden";
@@ -835,40 +835,40 @@ async function _$XfWxk(ctx: IContext) {
     }, 500)
 }
 
-async function pTWobY(ctx: IContext) {
+async function __vTpQGDw(ctx: IContext) {
     try {
-        if (!$jVksoCHS() && !_$sHuA()) {
-            return $KXTmgnjE(ctx);
+        if (!__mor() && !$TiDhB()) {
+            return OGuHjhL(ctx);
         }
     }
     catch (err) {
         if (debug) console.log("License check failed", err)
-        return $KXTmgnjE(ctx)
+        return OGuHjhL(ctx)
     }
-    if (debug) $KXTmgnjE(ctx)
+    if (debug) OGuHjhL(ctx)
 }
 
 
 
-async function $KXTmgnjE(ctx: IContext) {
+async function OGuHjhL(ctx: IContext) {
 
     // if the engine loads faster than the license check, we need to capture the ready event here
     let isReady = false;
     ctx.domElement.addEventListener("ready", () => isReady = true);
 
-    await _$cThps?.catch(() => { });
+    await eNaXOZj?.catch(() => { });
 
 
-    if ($jVksoCHS() || _$sHuA()) return;
-    if (KLnyx() === false) $vKd();
+    if (__mor() || $TiDhB()) return;
+    if (_yActo() === false) $xSLUxq();
 
     // check if the engine is already ready (meaning has finished loading)
     if (isReady) {
-        __OzoZ(ctx);
+        _$EZMmp(ctx);
     }
     else {
         ctx.domElement.addEventListener("ready", () => {
-            __OzoZ(ctx);
+            _$EZMmp(ctx);
         });
     }
 }
@@ -876,7 +876,7 @@ async function $KXTmgnjE(ctx: IContext) {
 // const licenseElementIdentifier = "needle-license-element";
 // const licenseDuration = 10000;
 // const licenseDelay = 1200;
-function __OzoZ(ctx: IContext) {
+function _$EZMmp(ctx: IContext) {
 
     const style = `
         position: relative;
@@ -889,7 +889,7 @@ function __OzoZ(ctx: IContext) {
         padding: 10px;
         padding-left: 30px;
     `;
-    if (__deG === "edu") {
+    if (yBXL === "edu") {
         if (navigator.webdriver) {
             console.log("This project is supported by Needle for Education – https://needle.tools");
         }
@@ -946,7 +946,7 @@ function __OzoZ(ctx: IContext) {
         }
     }, 1000);
 
-    if ($BZiUJx()) {
+    if (__cshwS()) {
         const removeDelay = 20_000;
         setLicenseTimeout(ctx, () => {
             clearInterval(interval);
@@ -955,7 +955,7 @@ function __OzoZ(ctx: IContext) {
             const intervalInMinutes = 5;
             setLicenseTimeout(ctx, () => {
                 if (ctx.domElement.parentNode)
-                    __OzoZ(ctx);
+                    _$EZMmp(ctx);
             }, 1000 * 60 * intervalInMinutes)
         }, removeDelay);
     }
@@ -966,7 +966,7 @@ function __OzoZ(ctx: IContext) {
 const base64Logo = "data:image/webp;base64,UklGRrABAABXRUJQVlA4WAoAAAAQAAAAHwAAHwAAQUxQSKEAAAARN6CmbSM4WR7vdARON11EBDq3fLiNbVtVzpMCPlKAEzsx0Y/x+Ovuv4dn0EFE/ydAvz6YggXzgh5sVgXM/zOC/4sii7qgGvB5N7hmuQYwkvazWAu1JPW41FXSHq6pnaQWvqYH18Fc0j1hO/BFTtIeSBlJi5w6qIIO7IOrwhFsB2Yxukif0FTRLpXswHR8MxbslKe9VZsn/Ub5C7YFOpqSTABWUDgg6AAAAFAGAJ0BKiAAIAA+7VyoTqmkpCI3+qgBMB2JbACdMt69DwMIQBLhkTO6XwY00UEDK6cNIDnuNibPf0EgAP7Y1myuiQHLDsF/0h5unrGh6WAbv7aegg2ZMd3uRKfT/3SJztcaujYfTvMXspfCTmYcoO6a+vhC3ss4M8uM58t4siiu59I4aOl59e9Sr6xoxYlHf2v+NnBNpJYeJf8jABQAId/PXuBkLEFkiCucgSGEcfhvajql/j3reCGl0M5/9gQWy7ayNPs+wlvIxFnNfSlfuND4CZOCyxOHhRqOmHN4ULHo3tCSrUNvgAA=";
 
 let lastLogTime = 0;
-async function $vKd(_logo?: string) {
+async function $xSLUxq(_logo?: string) {
     const now = Date.now();
     if (now - lastLogTime < 2000) return;
     lastLogTime = now;
@@ -999,7 +999,7 @@ async function $vKd(_logo?: string) {
 }
 
 
-async function _YuMDhu(context: IContext) {
+async function NNhYdA(context: IContext) {
     // isAllowed() now also covers cross-origin-isolated pages (where beacons can't be sent)
     // and Do Not Track / GPC.
     if (!Telemetry.isAllowed(context)) {
@@ -1013,7 +1013,7 @@ async function _YuMDhu(context: IContext) {
 
             // current url without query parameters
             const currentUrl = window.location.href.split("?")[0];
-            const license = __deG;
+            const license = yBXL;
 
             const beaconData = {
                 license,

package/src/engine/engine_loaders.gltf.ts

@@ -1,11 +1,11 @@
 
-import { addDracoAndKTX2Loaders as addDracoAndKTX2LoadersGLTFProgressive, configureLoader, createLoaders, setDracoDecoderLocation, setKTX2TranscoderLocation } from '@needle-tools/gltf-progressive';
+import { addDracoAndKTX2Loaders as addDracoAndKTX2LoadersGLTFProgressive, configureLoader, createLoaders, disposeLoaders, setDracoDecoderLocation, setKTX2TranscoderLocation } from '@needle-tools/gltf-progressive';
 import { MeshoptDecoder } from 'three/examples/jsm/libs/meshopt_decoder.module.js';
 import { DRACOLoader } from 'three/examples/jsm/loaders/DRACOLoader.js';
 import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js'
 import { KTX2Loader } from 'three/examples/jsm/loaders/KTX2Loader.js';
 
-import { Context } from "./engine_setup.js"
+import type { Context } from "./engine_setup.js"
 import { getParam } from "./engine_utils.js";
 
 const debug = getParam("debugdecoders");
@@ -20,6 +20,12 @@ function ensureLoaders() {
     return loaders;
 }
 
+/** Release shared decoder workers after the last engine context is destroyed. */
+export function disposeGLTFLoaders() {
+    disposeLoaders();
+    loaders = null;
+}
+
 export function setDracoDecoderPath(path: string | undefined) {
     if (path !== undefined && typeof path === "string") {
         setDracoDecoderLocation(path);

package/src/engine/engine_networking_blob.ts

@@ -1,7 +1,7 @@
 import { FileLoader } from "three";
 
 import { showBalloonWarning } from "./debug/index.js";
-import { KLnyx } from "./engine_license.js";
+import { _yActo } from "./engine_license.js";
 import { delay } from "./engine_utils.js";
 import { md5AsBytes, md5Hex, sha256Base64 } from "./engine_utils_hash.js";
 
@@ -45,7 +45,7 @@ export namespace BlobStorage {
      */
     export function canUpload(info: { filesize: number }) {
         const sizeInMB = info.filesize / 1024 / 1024;
-        if (KLnyx()) {
+        if (_yActo()) {
             return sizeInMB < maxSizeInMB;
         }
         return sizeInMB < maxFreeSizeInMB;
@@ -100,7 +100,7 @@ export namespace BlobStorage {
             console.warn(`Your file is too large for uploading (${filesizeInMB.toFixed(1)}MB). Max allowed size is ${maxSizeInMB}MB`);
             return null;
         }
-        else if (!KLnyx() && filesizeInMB > maxFreeSizeInMB) {
+        else if (!_yActo() && filesizeInMB > maxFreeSizeInMB) {
             if (opts?.silent !== true) showBalloonWarning(`File is too large for uploading. Please get a <a href=\"https://needle.tools/pricing\" target=\"_blank\">commercial license</a> to upload files larger than 5MB`);
             console.warn(`Your file is too large for uploading (${filesizeInMB.toFixed(1)}MB). Max size is 5MB for non-commercial users. Please get a commercial license at https://needle.tools/pricing for larger files (up to 50MB)`);
             return null;

package/src/engine/engine_physics.ts

@@ -183,6 +183,11 @@ export function setPhysicsEngineFactory(factory: ((context: Context) => IPhysics
 
 export class Physics {
 
+    /** Release the shared BVH worker pool after the last engine context is destroyed. */
+    static disposeMeshBVHWorkers() {
+        NEMeshBVH.disposeWorkers();
+    }
+
     private static _raycasting: number = 0;
     /**
      * Returns true if raycasting is currently in progress
@@ -805,7 +810,13 @@ namespace NEMeshBVH {
                                 })
                                 .finally(() => {
                                     if (debugPhysics) console.log(">>>>> worker done", name, { hasBoundsTre: geom.boundsTree != undefined });
-                                    availableWorkers.push(workerInstance);
+                                    if (retiredWorkers.has(workerInstance)) {
+                                        retiredWorkers.delete(workerInstance);
+                                        workerInstance.dispose();
+                                    }
+                                    else {
+                                        availableWorkers.push(workerInstance);
+                                    }
                                     copy.dispose();
                                     performance.mark("bvh.create.end");
                                     performance.measure("bvh.create (worker)", "bvh.create.start", "bvh.create.end");
@@ -926,6 +937,16 @@ namespace NEMeshBVH {
     const canUseWorkerSymbol = Symbol("Needle:MeshBVH-CanUseWorker");
     const workerInstances: GenerateMeshBVHWorker[] = [];
     const availableWorkers: GenerateMeshBVHWorker[] = [];
+    const retiredWorkers = new Set<GenerateMeshBVHWorker>();
+
+    export function disposeWorkers() {
+        for (const worker of workerInstances) {
+            if (worker.running) retiredWorkers.add(worker);
+            else worker.dispose();
+        }
+        workerInstances.length = 0;
+        availableWorkers.length = 0;
+    }
 
     function internalSetupWorker() {
         didSetupWorker = true;

package/src/engine/engine_utils_qrcode.ts

@@ -4,7 +4,7 @@ import { Quaternion, Vector2, Vector3, Vector4 } from "three";
 
 import { needleLogoOnlySVG } from "./assets/index.js";
 import { isDevEnvironment } from "./debug/debug.js";
-import { KLnyx } from "./engine_license.js";
+import { _yActo } from "./engine_license.js";
 import { InternalAttributeUtils } from "./engine_utils_attributes.js";
 import type { NeedleEngineWebComponent } from "./webcomponents/needle-engine.js";
 
@@ -135,7 +135,7 @@ async function internalRenderQRCodeOverlays(canvas: HTMLCanvasElement, args: { s
         console.debug("[QR Code] No web component found")
     }
 
-    const canUseCustomLogo = KLnyx();
+    const canUseCustomLogo = _yActo();
 
     // Query logo src from needle-engine attribute.
     // For any supported attribute it's possible to use "falsey" values (e.g. "0" or "false" to disable the logo in the QR code)

package/src/engine/project-document/engine_document_extensions.ts

@@ -0,0 +1,39 @@
+import type { DocumentDefContext, DocumentExtensionProvider } from '@needle-tools/addressing/document';
+
+/** Creates extension readers bound to each document's Engine context. */
+export interface DocumentExtensionRegistration {
+    readonly version: number;
+    readonly migrations?: DocumentExtensionProvider['migrations'];
+    readonly valueCodecs?: DocumentExtensionProvider['valueCodecs'];
+    readonly components?: {
+        createReader(context: DocumentDefContext): NonNullable<DocumentExtensionProvider['components']>['apply'] | undefined;
+    };
+}
+
+const extensions = new Map<string, DocumentExtensionRegistration>();
+
+/** Register before loading documents. Disposing affects subsequent evaluations. */
+export function registerDocumentExtensionProvider(id: string, provider: DocumentExtensionRegistration): { dispose(): void } {
+    if (!id.trim() || extensions.has(id)) throw new Error(`Invalid or duplicate document extension '${id}'.`);
+    if (!Number.isSafeInteger(provider.version) || provider.version < 1) throw new Error('Document extension version must be a positive integer.');
+    extensions.set(id, { ...provider });
+    let disposed = false;
+    return { dispose() {
+        if (disposed) return;
+        disposed = true;
+        extensions.delete(id);
+    } };
+}
+
+/** Bind readers at composition time, after asset loading and before activation. */
+export function resolveDocumentExtensions(context: DocumentDefContext): ReadonlyMap<string, DocumentExtensionProvider> {
+    const result = new Map<string, DocumentExtensionProvider>();
+    for (const [id, provider] of extensions) {
+        const apply = provider.components?.createReader(context);
+        result.set(id, { version: provider.version, migrations: provider.migrations,
+            valueCodecs: provider.valueCodecs,
+            ...(apply ? { components: { apply } } : {}),
+        });
+    }
+    return result;
+}

package/src/engine/project-document/engine_document_runtime.ts

@@ -57,7 +57,7 @@ export function createNeedleDocumentRuntime(context: Context): DocumentRuntime {
         createNode: () => new Object3D() as unknown as DocumentNode,
         createColor: value => new Color().fromArray(value),
         parse: async (data, src, options) => (await parseSync(context, data, src, null, options)) as unknown as DocumentModel | null,
-        instantiate(template, referenceId) {
+        clone(template, referenceId) {
             const provider: UIDProvider = {
                 seed: 0,
                 generateUUID: () => deriveStableId(referenceId, `seq:${provider.seed++}`),

package/src/engine/project-document/engine_project_document.ts

@@ -1,3 +1,4 @@
+import { joinPath, type NeedleAddress } from "@needle-tools/addressing";
 import {
     applyDef as applySharedDef,
     applyOver as applySharedOver,
@@ -16,6 +17,7 @@ import type { Object3D } from "three";
 import type { SerializationContext } from "../engine_serialization_core.js";
 import type { Context } from "../engine_setup.js";
 import type { Model } from "../engine_types.js";
+import { resolveDocumentExtensions } from './engine_document_extensions.js';
 import { createNeedleDocumentRuntime, documentDefContext } from "./engine_document_runtime.js";
 
 export { createDefSerializationContext } from "./engine_document_runtime.js";
@@ -43,17 +45,58 @@ export type ProjectEvaluationResult = Omit<SharedResult, "root" | "references" |
 };
 export type EvaluateProjectDocumentOptions = Omit<SharedOptions, "parent"> & { parent?: Object3D };
 
+type DocumentTarget = NonNullable<ProjectDocument["defs"]>[number]["target"];
+type DocumentDef = NonNullable<ProjectDocument["defs"]>[number];
+type DocumentOver = NonNullable<ProjectDocument["overs"]>[number];
+
+/** Documents saved before addressing 0.4 used namePath instead of the escaped path string. */
+function withLegacyPath<T extends { address?: NeedleAddress }>(target: T): T {
+    const address = target.address as (NeedleAddress & { namePath?: unknown }) | undefined;
+    if (address?.path !== undefined || !Array.isArray(address?.namePath) || !address.namePath.length
+        || !address.namePath.every((name): name is string => typeof name === "string")) return target;
+    return { ...target, address: { ...address, path: joinPath(address.namePath) } };
+}
+
+function withLegacyDef(def: DocumentDef): DocumentDef {
+    const target = withLegacyPath(def.target);
+    const copy = def.create?.copy;
+    const source = copy ? withLegacyPath(copy.source) : undefined;
+    if (target === def.target && source === copy?.source) return def;
+    return { ...def, target, create: copy && source ? { ...def.create, copy: { ...copy, source } } : def.create };
+}
+
+function withLegacyOver(over: DocumentOver): DocumentOver {
+    const target = withLegacyPath(over.target);
+    const value = over.value && typeof over.value === "object" && "address" in over.value
+        ? withLegacyPath(over.value as DocumentTarget) : over.value;
+    return target === over.target && value === over.value ? over : { ...over, target, value };
+}
+
+function withLegacyPaths(document: ProjectDocument): ProjectDocument {
+    return {
+        ...document,
+        references: document.references?.map(ref => {
+            const normalized = withLegacyPath(ref);
+            const parent = ref.parent ? withLegacyPath(ref.parent) : undefined;
+            return parent === ref.parent ? normalized : { ...normalized, parent };
+        }),
+        defs: document.defs?.map(withLegacyDef),
+        overs: document.overs?.map(withLegacyOver),
+    };
+}
+
 /** Engine entry point: preserve pre-awake scheduling through the runtime adapter. */
 export async function evaluateProjectDocument(context: Context, document: ProjectDocument, options?: EvaluateProjectDocumentOptions): Promise<ProjectEvaluationResult> {
-    return await evaluateShared(createNeedleDocumentRuntime(context), document, options as unknown as SharedOptions) as unknown as ProjectEvaluationResult;
+    return await evaluateShared(createNeedleDocumentRuntime(context), withLegacyPaths(document),
+        { ...options, extensions: options?.extensions ?? resolveDocumentExtensions } as unknown as SharedOptions) as unknown as ProjectEvaluationResult;
 }
 
 export function applyDef(def: NonNullable<ProjectDocument["defs"]>[number], root: Object3D, references: Map<string, Object3D>, issue: (arc: "def", message: string) => void, serializationContext: SerializationContext): void {
-    applySharedDef(def, root as unknown as DocumentNode, references as unknown as Map<string, DocumentNode>, issue, documentDefContext(serializationContext));
+    applySharedDef(withLegacyDef(def), root as unknown as DocumentNode, references as unknown as Map<string, DocumentNode>, issue, documentDefContext(serializationContext));
 }
 
 export function applyOver(context: Context, over: NonNullable<ProjectDocument["overs"]>[number], root: Object3D, references: Map<string, Object3D>, state: OverApplyState, issue: (arc: "over", message: string) => void): void {
-    applySharedOver(createNeedleDocumentRuntime(context), over, root as unknown as DocumentNode, references as unknown as Map<string, DocumentNode>, state, issue);
+    applySharedOver(createNeedleDocumentRuntime(context), withLegacyOver(over), root as unknown as DocumentNode, references as unknown as Map<string, DocumentNode>, state, issue);
 }
 
 export function resolveMaterialEntity(model: Model, address: import("@needle-tools/addressing").NeedleAddress): Promise<object | null> {

package/src/engine/webcomponents/needle menu/needle-menu-spatial.ts

@@ -2,7 +2,7 @@ import { Mesh, Object3D, TextureLoader, Vector4 } from "three";
 import ThreeMeshUI from "three-mesh-ui";
 
 import { addNewComponent } from "../../engine_components.js";
-import { KLnyx } from "../../engine_license.js";
+import { _yActo } from "../../engine_license.js";
 import { OneEuroFilterXYZ } from "../../engine_math.js";
 import type { Context } from "../../engine_setup.js";
 import { lookAtObject } from "../../engine_three_utils.js";
@@ -321,7 +321,7 @@ export class NeedleSpatialMenu {
         }
         if (this.menu) {
             const index = this.menu.children.indexOf(this._poweredByNeedleElement as any);
-            if (!this._showNeedleLogo && KLnyx()) {
+            if (!this._showNeedleLogo && _yActo()) {
                 if (index >= 0) {
                     this._poweredByNeedleElement.removeFromParent();
                     this.markDirty();