@needle-tools/addressing 0.3.4 → 0.4.0

package/src/document/evaluate.ts

@@ -0,0 +1,998 @@
+import { resolveDocumentCollectionElement } from "./collectionSelector.js";
+import { attachNeedleIdsToLoadedGltf, resolveInCollection, resolveInGraph, type AddressableElement, type GraphNode, type NeedleAddress } from "../index.js";
+import { PROJECT_DOCUMENT_KEY, isProjectDocument, resolveDocumentRemoteSrc, type ProjectDocument, type ProjectDocumentReference, type ProjectDocumentTarget, type ProjectDocumentOver, type ProjectEvaluationIssue, type ProjectEvaluationResult, type EvaluateProjectDocumentOptions } from "./types.js";
+import type { DocumentNode as Object3D, DocumentModel as Model, DocumentRuntime as Context, DocumentDefContext as SerializationContext } from "./runtime.js";
+import { createProjectDocumentInspection, registerProjectDocumentInspection } from "./inspection.js";
+
+/** Shared asset/entity preparation; does not place nodes into the host scene. */
+export function createDocumentAssetLoader(
+    context: Pick<Context, "parse" | "parkTemplate" | "loadEnvironment">,
+    document: ProjectDocument,
+    options: EvaluateProjectDocumentOptions | undefined,
+    issue: (arc: ProjectEvaluationIssue["arc"], message: string) => void,
+) {
+    // Per-asset parse options: threads the host's resolveAssetUrl (asset-service resolveUrl)
+    // to parseSync so an asset's resources resolve at load time. Undefined when no rewrite is
+    // provided, so parseSync keeps its plain relative resolution.
+    const parseOptionsFor = (assetId: string) =>
+        options?.resolveAssetUrl ? { resolveUrl: (url: string) => options.resolveAssetUrl!(assetId, url) } : undefined;
+
+    // ---- references: load assets (cached per asset id), place roots ----
+    // aggregate download progress across all asset fetches: every chunk updates the
+    // asset's {loaded, total} slot and reports the SUMS — one bar over the whole set
+    const progressByAsset = new Map<string, { loaded: number; total: number }>();
+    const reportProgress = () => {
+        if (!options?.onProgress) return;
+        let loaded = 0, total = 0;
+        for (const entry of progressByAsset.values()) {
+            loaded += entry.loaded;
+            total += entry.total;
+        }
+        options.onProgress(loaded, total);
+    };
+
+    const assetData = new Map<string, Promise<ArrayBuffer | string | null>>();
+    const loadAssetData = (assetId: string): Promise<ArrayBuffer | string | null> => {
+        let pending = assetData.get(assetId);
+        if (!pending) {
+            const src = document.assets?.[assetId]?.src;
+            if (typeof src !== "string") {
+                pending = Promise.resolve(null);
+            }
+            else if (options?.resolveAsset) {
+                pending = options.resolveAsset(assetId, src).catch(err => {
+                    issue("reference", `asset "${assetId}" failed to resolve: ${err}`);
+                    return null;
+                });
+            }
+            else if (resolveDocumentRemoteSrc(src, document.remotes, options?.remotes) === null) {
+                // deployed-viewer incident 2026-08-17: the raw scheme reached
+                // fetch() and every over inside the reference cascade-failed
+                issue("reference", `asset "${assetId}" src "${src}" names a remote that is not in the document's remotes table — the asset is skipped`);
+                pending = Promise.resolve(null);
+            }
+            else {
+                const resolvedSrc = resolveDocumentRemoteSrc(src, document.remotes, options?.remotes)!;
+                const url = options?.baseUrl ? new URL(resolvedSrc, options.baseUrl).href : resolvedSrc;
+                pending = fetch(url).then(res => {
+                    if (!res.ok) throw new Error(`${res.status} ${res.statusText}`);
+                    // SPA/dev servers answer MISSING files with 200 + their index.html —
+                    // without this check that surfaces later as a cryptic gltf parse
+                    // error ("Unexpected token '<' … is not valid JSON")
+                    const contentType = res.headers.get("Content-Type") ?? "";
+                    if (contentType.includes("text/html")) {
+                        throw new Error(`the server answered with an HTML page (Content-Type: ${contentType}) — the file probably does not exist there. Documents record srcs AS SAVED: a dev-server url (e.g. localhost) does not exist on a deployment.`);
+                    }
+                    // stream so the download reports byte progress; fall back to a
+                    // plain buffer read when the body is not streamable
+                    if (!res.body || !options?.onProgress) return res.arrayBuffer();
+                    const slot = { loaded: 0, total: Number(res.headers.get("Content-Length")) || 0 };
+                    progressByAsset.set(assetId, slot);
+                    reportProgress();
+                    return readBodyWithProgress(res.body, received => {
+                        slot.loaded = received;
+                        // servers without Content-Length: keep total >= loaded so the
+                        // bar never exceeds 100% (it jumps to done at the end)
+                        if (slot.total < received) slot.total = received;
+                        reportProgress();
+                    });
+                }).catch(err => {
+                    issue("reference", `asset "${assetId}" failed to load from ${url}: ${err}`);
+                    return null;
+                });
+            }
+            assetData.set(assetId, pending);
+        }
+        return pending;
+    };
+
+    // parse-once cache: EVERY consumer — placed references, entity references, assets
+    // loaded on demand by overs — shares one parsed TEMPLATE per asset id. Placed
+    // references then INSTANTIATE per-reference copies from it (shared geometry/
+    // materials/textures, per-copy stable guids).
+    const parsedAssets = new Map<string, Promise<Model | null>>();
+    const loadParsedAsset = (assetId: string, arc: ProjectEvaluationIssue["arc"] = "over"): Promise<Model | null> => {
+        let pending = parsedAssets.get(assetId);
+        if (!pending) {
+            pending = (async () => {
+                // three DISTINGUISHABLE failure modes — an opaque "failed to load" cost a
+                // debugging session (missing assets-map entry read as a network problem)
+                if (!document.assets?.[assetId]) {
+                    issue(arc, `asset "${assetId}" has no entry in the document's assets map`);
+                    return null;
+                }
+                const data = await loadAssetData(assetId);
+                if (data === null) return null; // fetch failure already reported by loadAssetData
+                // parse with the RESOLVED src, so a remote asset's own relative
+                // resources (textures, external buffers) resolve at its location
+                const rawSrc = document.assets[assetId].src ?? assetId;
+                const src = resolveDocumentRemoteSrc(rawSrc, document.remotes, options?.remotes) ?? rawSrc;
+                const model = (await context.parse(data, src, parseOptionsFor(assetId))) ?? null;
+                if (!model) issue(arc, `asset "${assetId}" data loaded but PARSING failed (see console for the parser error)`);
+                if (model) {
+                    if (model.parser?.json) attachNeedleIdsToLoadedGltf(model.parser.json, model.parser.associations, model.scenes);
+                    // Park the template: a DETACHED scene still counts as active hierarchy
+                    // (engine-test-pinned), so its queued components would AWAKE on the next
+                    // pump in a running context. Deactivate in the same synchronous turn as
+                    // the parse resolution — before any frame can run them. Copies are
+                    // instantiated INTO the parked template (no awake) and re-activated
+                    // after reparenting; the template itself is destroyed once all
+                    // references are instantiated. Material-only glbs parse WITHOUT a
+                    // scene — nothing to park.
+                    if (model.scene) context.parkTemplate(model.scene);
+                }
+                return model;
+            })();
+            parsedAssets.set(assetId, pending);
+        }
+        return pending;
+    };
+
+    // ---- ENTITY references (with an address): instantiate into the entity pool -----
+    // Not placed in the graph. One promise per id — every consumer (assign values,
+    // entity-targeted overs) chains on the same instantiation, so N users share ONE
+    // runtime instance by construction and assign/patch ordering stops being temporal.
+    const entities = new Map<string, Promise<object | null>>();
+    for (const ref of document.references ?? []) {
+        if (!ref || typeof ref.id !== "string" || typeof ref.asset !== "string" || !ref.address) continue;
+        if (entities.has(ref.id)) {
+            issue("reference", `duplicate reference id "${ref.id}" — entry skipped`);
+            continue;
+        }
+        const address = ref.address;
+        entities.set(ref.id, (async (): Promise<object | null> => {
+            if (address.type === "material") {
+                const model = await loadParsedAsset(ref.asset);
+                if (!model) return null; // load/parse failure already reported
+                const material = await resolveMaterialEntity(model, address);
+                if (!material) issue("reference", `entity "${ref.id}": material did not resolve in asset "${ref.asset}" (${JSON.stringify(address)})`);
+                return material;
+            }
+            if (address.type === "hdr") {
+                // WHOLE-ASSET entity (address is only a type): the asset itself,
+                // instantiated as an environment texture (PMREM — hdr/exr/ktx2).
+                // The src rides the SAME resolution ladder as placed assets
+                // (editor hook, then remotes + document base) — the raw src
+                // reaching loadPMREM meant every relative/virtual environment
+                // silently failed to instantiate on reload (2026-08-18).
+                const src = document.assets?.[ref.asset]?.src;
+                if (typeof src !== "string") {
+                    issue("reference", `entity "${ref.id}": unknown asset "${ref.asset}"`);
+                    return null;
+                }
+                let url: string;
+                let revoke: (() => void) | undefined;
+                if (options?.resolveAsset) {
+                    const data = await options.resolveAsset(ref.asset, src).catch(err => {
+                        issue("reference", `entity "${ref.id}": asset "${ref.asset}" failed to resolve: ${err}`);
+                        return null;
+                    });
+                    if (data === null) return null;
+                    if (typeof data === "string") url = data;
+                    else {
+                        // loadPMREM sniffs content type on extensionless urls,
+                        // so a bare blob of hdr/exr/ktx2 bytes routes correctly
+                        const blobUrl = URL.createObjectURL(new Blob([data]));
+                        url = blobUrl;
+                        revoke = () => URL.revokeObjectURL(blobUrl);
+                    }
+                }
+                else {
+                    const resolvedSrc = resolveDocumentRemoteSrc(src, document.remotes, options?.remotes);
+                    if (resolvedSrc === null) {
+                        issue("reference", `entity "${ref.id}": src "${src}" names a remote that is not in the document's remotes table — the entity is skipped`);
+                        return null;
+                    }
+                    url = options?.baseUrl ? new URL(resolvedSrc, options.baseUrl).href : resolvedSrc;
+                }
+                // the DOCUMENT src is the identity that still carries meaning —
+                // the resolved url may be a blob: of raw bytes, where loadPMREM's
+                // url sniffing can neither see the ".pmrem." marker (a prefiltered
+                // atlas would come back equirect-mapped) nor a usable filename
+                // (the texture would be labeled by a uuid). Pass both explicitly.
+                const srcPath = src.split(/[?#]/)[0];
+                const srcName = srcPath.substring(srcPath.lastIndexOf("/") + 1) || undefined;
+                const format = /pmrem/i.test(src) ? "pmrem" as const : undefined;
+                const texture = await context.loadEnvironment(url, { format, name: srcName }).finally(() => revoke?.());
+                if (!texture) issue("reference", `entity "${ref.id}": environment texture failed to load from ${src}`);
+                return texture;
+            }
+            issue("reference", `entity "${ref.id}": element type "${address.type ?? "?"}" is not instantiable yet`);
+            return null;
+        })());
+    }
+
+    return { loadParsedAsset, entities };
+}
+
+/**
+ * Evaluate a project document into the given context. One-shot; never throws for
+ * content issues (they are collected in the result), only for a non-document input.
+ *
+ * Order (plans/project-format-v0.md): load + place references (document order) →
+ * mounts → [pre-setup phase:] asset component deserialization (the engine's own
+ * queue, FIFO) → defs → overs. Resolution is scoped to the target reference's
+ * subtree; misses are reported and skipped (exact resolution only in v0).
+ */
+export async function evaluateProjectDocument(context: Context, document: ProjectDocument, options?: EvaluateProjectDocumentOptions): Promise<ProjectEvaluationResult> {
+    if (!isProjectDocument(document)) {
+        throw new TypeError(`evaluateProjectDocument: not a project document (missing "${PROJECT_DOCUMENT_KEY}")`);
+    }
+
+    const root = options?.parent ?? (context.scene as unknown as Object3D);
+    const inspection = createProjectDocumentInspection(context.scene as unknown as Object3D);
+    const references = new Map<string, Object3D>(options?.referenceBindings as ReadonlyMap<string, Object3D> | undefined);
+    const models = new Map<string, Model>();
+    const issues: ProjectEvaluationIssue[] = [];
+    const issue = (arc: ProjectEvaluationIssue["arc"], message: string) => { issues.push({ arc, message }); };
+
+    const { loadParsedAsset, entities } = createDocumentAssetLoader(context, document, options, issue);
+
+    // Placed references: parse ONCE per asset (template, via loadParsedAsset), then
+    // INSTANTIATE per reference — deferred to the pre-setup phase so clones copy FULLY
+    // DESERIALIZED template components (the loader's queued deserialization runs first,
+    // FIFO). Each copy gets STABLE, ORDER-INDEPENDENT guids derived from the reference
+    // id carried in the document: deriveStableId(ref.id, originalFileGuid) — same
+    // guids on every client and load (engine-global lookups, networking ownership).
+    const pendingPlacements: Array<{ ref: ProjectDocumentReference; model: Model }> = [];
+    const pendingIds = new Set<string>();
+    for (const ref of document.references ?? []) {
+        if (!ref || typeof ref.id !== "string" || typeof ref.asset !== "string") {
+            issue("reference", `invalid reference entry: ${JSON.stringify(ref)}`);
+            continue;
+        }
+        if (ref.address) continue; // entity reference — pooled above, never placed
+        if (pendingIds.has(ref.id)) {
+            issue("reference", `duplicate reference id "${ref.id}" — entry skipped`);
+            continue;
+        }
+        if (options?.referenceBindings) {
+            const bound = options.referenceBindings.get(ref.id);
+            if (!bound) { issue("reference", `reference "${ref.id}": no existing model binding supplied`); continue; }
+            if (!document.assets?.[ref.asset]) { issue("reference", `reference "${ref.id}": unknown asset "${ref.asset}"`); continue; }
+            pendingIds.add(ref.id);
+            references.set(ref.id, bound);
+            models.set(ref.id, { scene: bound });
+            continue;
+        }
+        const model = await loadParsedAsset(ref.asset, "reference");
+        if (!model) {
+            // load/parse failure reported by loadParsedAsset (unknown asset, fetch, parser)
+            continue;
+        }
+        if (!model.scene) {
+            issue("reference", `reference "${ref.id}": asset "${ref.asset}" did not produce a scene`);
+            continue;
+        }
+        pendingIds.add(ref.id);
+        pendingPlacements.push({ ref, model });
+    }
+
+    // ---- instantiate + mounts + defs + overs: the engine's pre-setup phase ---
+    // The templates' own components deserialize in pre-setup callbacks the loader
+    // queued during parseSync (FIFO) — queuing AFTER the loads guarantees this
+    // callback sees fully deserialized templates, and still runs strictly before awake.
+    const completed = new Promise<void>((resolve) => {
+        context.schedule(() => {
+            // instantiate ALL copies FIRST, attach + activate afterwards: each
+            // instantiate() pumps processNewScripts, which awakens ACTIVE components in
+            // a running context — an already-activated copy A would awake mid-callback
+            // (before defs/overs) while copy B instantiates. All copies stay parked
+            // (inherited from the deactivated template) until the last pump inside this
+            // callback has happened; awake then follows at the engine's next natural
+            // pump, strictly after the document opinions below.
+            const placedCopies: Object3D[] = [];
+            for (const { ref, model } of pendingPlacements) {
+                const template = model.scene as unknown as Object3D;
+                const placed = context.instantiate(template, ref.id);
+                if (!placed) {
+                    issue("reference", `reference "${ref.id}": instantiating asset "${ref.asset}" failed`);
+                    continue;
+                }
+                references.set(ref.id, placed);
+                // per-reference Model view: parser/animations from the shared template,
+                // scene = THIS reference's instance (what editor open-file tracking needs)
+                models.set(ref.id, { ...model, scene: placed } as unknown as Model);
+                // Keep parser.associations valid for the copy: the loader keyed the
+                // TEMPLATE's objects, but tooling (editor source-asset attribution)
+                // looks up the PLACED instances. Materials/meshes/textures are shared
+                // with the template, so their keys stay valid — only Object3D keys
+                // need mirroring. instantiate preserves child order, so a parallel
+                // walk pairs template nodes with their copies.
+                const associations = (model as unknown as { parser?: { associations?: Map<object, unknown> } }).parser?.associations;
+                if (associations) {
+                    const mirror = (a: Object3D, b: Object3D) => {
+                        const record = associations.get(a);
+                        if (record !== undefined) associations.set(b, record);
+                        const count = Math.min(a.children.length, b.children.length);
+                        for (let i = 0; i < count; i++) mirror(a.children[i], b.children[i]);
+                    };
+                    mirror(template, placed);
+                }
+                placedCopies.push(placed);
+            }
+            for (const placed of placedCopies) {
+                root.add(placed);
+                // undo only the park flag inherited from the template root — authored
+                // visibility lives on deeper nodes and is preserved by the clone
+                context.activateInstance(placed);
+            }
+
+            // mounts (after all placements so forward references work)
+            // placement TRS is ordinary overs on the placed root — no transform pass here
+            // DEPRECATED READ (2026-08-03, remove soon): `reference.parent` was replaced
+            // by parent OVERS below days after shipping; only unreleased documents from
+            // that week carry it. The writer no longer emits it.
+            for (const ref of document.references ?? []) {
+                const placed = ref?.id ? references.get(ref.id) : undefined;
+                if (!placed) continue;
+                if (ref.parent) {
+                    const host = references.get(ref.parent.ref);
+                    if (!host) {
+                        issue("reference", `reference "${ref.id}": parent ref "${ref.parent.ref}" not placed — staying at the composition root`);
+                    }
+                    else {
+                        // no address = mount at the host reference's ROOT (resolveInGraph
+                        // returns null for an empty address — it never means "the root")
+                        const mount = ref.parent.address
+                            ? resolveInGraph(ref.parent.address, host as unknown as GraphNode) as unknown as Object3D | null
+                            : host as unknown as Object3D;
+                        if (!mount) {
+                            issue("reference", `reference "${ref.id}": parent address did not resolve in "${ref.parent.ref}" — staying at the composition root`);
+                        }
+                        else {
+                            mount.add(placed);
+                        }
+                    }
+                }
+            }
+
+            // the placement templates served their purpose — destroy them so their
+            // dormant registered components are cleanly unregistered. dispose=false:
+            // geometries/materials/textures are SHARED with the instantiated copies.
+            const destroyedTemplates = new Set<object>();
+            for (const { model } of pendingPlacements) {
+                if (model.scene && !destroyedTemplates.has(model.scene)) {
+                    destroyedTemplates.add(model.scene);
+                    context.disposeTemplate(model.scene);
+                }
+            }
+
+            // sync opinions (defs, property/active overs) apply strictly before awake;
+            // async ones (reference-valued material overs → load the material asset) run
+            // after and settle `completed`. applyOvers does its sync pass before the
+            // first await, so ordering for non-async overs is preserved.
+            applyDefs(context, document, root, references, issue, options?.baseUrl);
+            // Bind before mutations: original-scene paths can change during this batch.
+            const sceneTargets = new Map<ProjectDocumentTarget, Object3D | null>();
+            for (const over of document.overs ?? []) {
+                for (const target of [over?.target, over?.value as ProjectDocumentTarget | null]) {
+                    if (target?.address && (target.ref === "$scene" || (target.ref !== undefined && options?.referenceBindings?.has(target.ref)))) {
+                        const scope = over?.target?.path === "parent" ? root : context.scene;
+                        sceneTargets.set(target, resolveTargetObject(target, root, references, scope));
+                    }
+                }
+            }
+            const oversApplied = applyOvers(context, document, root, references, entities, issue, sceneTargets);
+            // PARENT OVERS run LAST: defs and property overs resolve their targets
+            // WITHIN reference scopes, so nodes must still sit inside their containers
+            // when those resolve (an async fn runs synchronously until its first await,
+            // so applyOvers' sync pass has completed here; async overs are
+            // entity/material work and never touch node parents). Flat-model
+            // consequence: content children are pulled out to the composition root
+            // only after every scoped target found them.
+            if (inspection) {
+                const referenceRoots = new Set(references.values());
+                for (const [ref, placed] of references) {
+                    const model = models.get(ref) as unknown as { parser?: { associations?: Map<object, unknown> }; animations?: object[] } | undefined;
+                    inspection.registerReference(ref, placed, [
+                        ...(model?.parser?.associations?.keys() ?? []),
+                        ...(model?.animations ?? []),
+                    ], referenceRoots);
+                }
+            }
+            applyParentOvers(document, root, references, issue, sceneTargets);
+            oversApplied.finally(() => resolve());
+        });
+    });
+
+    if (inspection) {
+        inspection.ready = completed.then(async () => {
+            for (const [ref, entity] of entities) {
+                const resolved = await entity;
+                if (resolved) inspection.registerReference(ref, resolved);
+            }
+        });
+        registerProjectDocumentInspection(context.inspectionOwner ?? context, inspection);
+    }
+    return { root, references, models, issues, completed };
+}
+
+// ---------------------------------------------------------------------------
+// target resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * PARENT OVERS — the one structural rail (needle-editor plans/flat-scene-model.md):
+ * `{ target: { ref, address?, path: "parent" }, value: { ref | "$scene", address?,
+ * index? } }` reparents the target node under the value's node. Runs AFTER defs and
+ * the sync over pass (scoped targets must resolve while nodes still sit inside their
+ * containers), in ascending-index order: document nodes end up in the recorded
+ * RELATIVE order; foreign nodes (editor helpers) keep their positions and are not
+ * counted. Plain `add` (not attach): local TRS is authored by ordinary overs,
+ * parent-relative. An unresolvable side parks the node where it is + reports —
+ * never a load failure.
+ */
+function applyParentOvers(document: ProjectDocument, root: Object3D, references: Map<string, Object3D>, issue: (arc: "over", message: string) => void, sceneTargets: ReadonlyMap<ProjectDocumentTarget, Object3D | null>): void {
+    const parentOvers = (document.overs ?? []).filter(over => over?.target?.path === "parent");
+    const overIndex = (over: ProjectDocumentOver): number => {
+        const index = (over.value as { index?: unknown } | null | undefined)?.index;
+        return typeof index === "number" ? index : Number.MAX_SAFE_INTEGER;
+    };
+    parentOvers.sort((a, b) => overIndex(a) - overIndex(b));
+    for (const over of parentOvers) {
+        const node = sceneTargets.has(over.target) ? sceneTargets.get(over.target) : resolveTargetObject(over.target, root, references);
+        if (!node) {
+            issue("over", `parent over target did not resolve: ${JSON.stringify(over.target)}`);
+            continue;
+        }
+        const value = over.value as { ref?: string; address?: NeedleAddress } | null | undefined;
+        if (!value || typeof value !== "object") {
+            issue("over", `parent over value must be a node reference: ${JSON.stringify(over.value)}`);
+            continue;
+        }
+        let parent: Object3D | null = null;
+        if (value.ref === undefined || value.ref === "$scene") {
+            // the composition root — where placements land (NOT context.scene:
+            // an embedded evaluation with options.parent must stay contained)
+            parent = sceneTargets.has(value) ? sceneTargets.get(value) ?? null : value.address
+                ? resolveInGraph(value.address, root as unknown as GraphNode) as unknown as Object3D | null
+                : root;
+        }
+        else {
+            const host = references.get(value.ref);
+            if (host) {
+                parent = value.address
+                    ? resolveInGraph(value.address, host as unknown as GraphNode) as unknown as Object3D | null
+                    : host as unknown as Object3D;
+            }
+        }
+        if (!parent) {
+            issue("over", `parent over did not resolve its new parent — staying in place: ${JSON.stringify(over.value)}`);
+            continue;
+        }
+        if (parent === node || isAncestorOf(node, parent)) {
+            issue("over", `parent over would create a cycle — ignored: ${JSON.stringify(over.target)}`);
+            continue;
+        }
+        parent.add(node);
+    }
+}
+
+/** is `node` an ancestor of `candidate` (used to refuse cycle-creating parent overs) */
+function isAncestorOf(node: Object3D, candidate: Object3D): boolean {
+    for (let current: Object3D | null = candidate.parent; current; current = current.parent) {
+        if (current === node) return true;
+    }
+    return false;
+}
+
+function resolveTargetObject(target: ProjectDocumentTarget | undefined, root: Object3D, references: Map<string, Object3D>, scene?: Object3D | null): Object3D | null {
+    // reserved ref: the CONTEXT SCENE — same semantics as the "$scene" over
+    // branch (scene-level defs, e.g. components on the composition scene root)
+    const scope = target?.ref === "$scene" ? (scene ?? root)
+        : target?.ref !== undefined ? references.get(target.ref)
+            : root;
+    if (!scope) return null;
+    if (!target?.address) return scope;
+    return resolveInGraph(target.address, scope as unknown as GraphNode) as unknown as Object3D | null;
+}
+
+// ---------------------------------------------------------------------------
+// property paths
+// ---------------------------------------------------------------------------
+
+/** `<field>:<value>` — matches an element of a collection by one of its fields */
+const QUALIFIER = /^([A-Za-z_][A-Za-z0-9_-]*):([\s\S]*)$/;
+
+export function splitPath(path: string): string[] {
+    // "~1" → "/" and "~0" → "~" (RFC 6901 escaping, unescaped in that order)
+    return path.split("/").filter(s => s.length > 0).map(s => s.replace(/~1/g, "/").replace(/~0/g, "~"));
+}
+
+/**
+ * Advance one path segment. Objects take the segment as a literal key; COLLECTIONS take
+ * either a numeric index or a `<field>:<value>` qualifier. Qualifier parsing is confined
+ * to collections, so a plain object property whose name contains ":" is never mistaken
+ * for one.
+ */
+function stepPath(context: Context, current: unknown, segment: string, refScope: string | undefined, report: (message: string) => void): unknown {
+    // synthesized: a node's components, without exposing the userData layout
+    if ((current as Object3D | undefined)?.isObject3D === true && segment === "components") {
+        return context.getComponents?.(current as Object3D) ?? [];
+    }
+    if (!Array.isArray(current)) {
+        return (current as Record<string, unknown> | undefined)?.[segment];
+    }
+    return resolveDocumentCollectionElement(current, segment, {
+        matchesComponentType: context.matchesComponentType?.bind(context),
+        matchesComponentGuid: context.matchesComponentGuid?.bind(context),
+        deriveComponentGuid: context.deriveComponentGuid?.bind(context),
+        referenceId: refScope,
+        report,
+    });
+}
+
+/** walk every segment but the last; returns the container holding the final key */
+function walkPath(context: Context, element: object, segments: string[], refScope: string | undefined, report: (message: string) => void): { container: object; chain: object[] } | null {
+    const chain: object[] = [element];
+    let current: unknown = element;
+    for (let i = 0; i < segments.length - 1; i++) {
+        const next = stepPath(context, current, segments[i], refScope, message => report(`at "${segments[i]}": ${message}`));
+        if (!next || typeof next !== "object") {
+            report(`does not resolve at "${segments[i]}"`);
+            return null;
+        }
+        current = next;
+        chain.push(next as object);
+    }
+    return { container: current as object, chain };
+}
+
+/** a live three material, seen through the addressing package's duck type */
+type MaterialElement = AddressableElement & Record<string, unknown>;
+
+/** every distinct material used anywhere under `root`, in traversal order */
+function collectMaterials(root: Object3D): MaterialElement[] {
+    const materials: MaterialElement[] = [];
+    root.traverse(obj => {
+        const material = (obj as unknown as { material?: unknown }).material;
+        for (const m of Array.isArray(material) ? material : material ? [material] : []) {
+            if (m && typeof m === "object" && !materials.includes(m as MaterialElement)) {
+                materials.push(m as MaterialElement);
+            }
+        }
+    });
+    return materials;
+}
+
+/** materials are not scene-graph nodes — resolve them against the meshes of the scope
+ *  (plus any subtrees deactivation detached from it: the material resource outlives
+ *  its consumer's presence in the composed result) */
+function resolveTargetMaterial(scope: Object3D, address: NeedleAddress, detachedRoots?: readonly Object3D[]): { material: Record<string, unknown> } | null {
+    // ONE ladder for every element type (anchor → id → name), from the addressing
+    // package — materials used to carry their own, which is why anchoring a material
+    // had no effect and why the two material resolvers here disagreed about whether a
+    // name match had to be unique.
+    const materials = collectMaterials(scope);
+    for (const detached of detachedRoots ?? []) {
+        for (const material of collectMaterials(detached)) {
+            if (!materials.includes(material)) materials.push(material);
+        }
+    }
+    const material = resolveInCollection(address, materials);
+    return material ? { material: material as Record<string, unknown> } : null;
+}
+
+// ---------------------------------------------------------------------------
+// defs
+// ---------------------------------------------------------------------------
+
+function applyDefs(context: Context, document: ProjectDocument, root: Object3D, references: Map<string, Object3D>, issue: (arc: "def", message: string) => void, baseUrl?: string) {
+    const defs = document.defs ?? [];
+    if (!defs.length) return;
+    const serializationContext = createDefSerializationContext(context, root, baseUrl);
+    for (const def of defs) {
+        applyDef(def, root, references, issue, serializationContext);
+    }
+}
+
+/**
+ * The serialization context ONE def application (or a whole document's worth)
+ * deserializes through: rooted at the COMPOSITION root so `{guid}` references in
+ * def data resolve across the whole composed result (cross-reference wiring).
+ * `baseUrl`: URL-string component fields (e.g. a tracked image's remote object) go
+ * through the EXISTING AssetReference.getOrCreate deserialization — it needs a
+ * source id to resolve document-relative urls against (no new loading path).
+ */
+export function createDefSerializationContext(context: Context, root: Object3D, baseUrl?: string): SerializationContext {
+    return context.createDefContext?.(root, baseUrl) ?? {
+        scene: context.scene,
+        createNode: () => context.createNode(),
+    };
+}
+
+/**
+ * Apply ONE def to the live composition — create/adopt the node, then
+ * instantiate/adopt its components. Exported as the single-arc primitive:
+ * document evaluation loops over it, and the op-bridge APPLICATOR applies a
+ * creation op's carried def through exactly this function (one implementation,
+ * plans/operation-bridge.md fixture 2).
+ */
+export function applyDef(def: NonNullable<ProjectDocument["defs"]>[number], root: Object3D, references: Map<string, Object3D>, issue: (arc: "def", message: string) => void, serializationContext: SerializationContext): void {
+    {
+        let obj = resolveTargetObject(def?.target, root, references, serializationContext.scene);
+        if (!obj) {
+            issue("def", `def target did not resolve: ${JSON.stringify(def?.target)}`);
+            return;
+        }
+        if (def.create) {
+            if (def.create.copy) {
+                // Reproducing a duplicate needs the host's clone command: it owns
+                // component/runtime identity and batch reference retargeting.
+                issue("def", "copy definitions require a host duplication command");
+                return;
+            }
+            // the def DEFINES a node under the resolved parent (USD-proper def). When a
+            // child with the same name ALREADY exists it is ADOPTED (transform applied,
+            // components deserialize onto matching existing instances below) — a def
+            // over an existing prim composes onto it. This is how the start-camera def
+            // takes over the engine's own camera instead of creating a twin.
+            const children = obj.children as Object3D[] | undefined;
+            const existing = (typeof def.create.id === "string"
+                ? children?.find(c => c?.userData?.["needle-id"] === def.create!.id)
+                : undefined) ?? (typeof def.create.name === "string"
+                ? children?.find(c => c?.name === def.create!.name)
+                : undefined);
+            const node = existing ?? serializationContext.createNode();
+            if (!existing) {
+                if (typeof def.create.name === "string") node.name = def.create.name;
+                obj.add(node);
+            }
+            if (typeof def.create.id === "string") node.userData["needle-id"] = def.create.id;
+            if (Array.isArray(def.create.position) && def.create.position.length >= 3) node.position.fromArray(def.create.position);
+            if (Array.isArray(def.create.quaternion) && def.create.quaternion.length >= 4) node.quaternion.fromArray(def.create.quaternion);
+            if (Array.isArray(def.create.scale) && def.create.scale.length >= 3) node.scale.fromArray(def.create.scale);
+            obj = node;
+        }
+        for (const compData of def.components ?? []) {
+            if (!compData || typeof compData.name !== "string") {
+                issue("def", `invalid component entry: ${JSON.stringify(compData)}`);
+                continue;
+            }
+            // NODE REFERENCES ({ref: <reference id>, address?}) resolve to LIVE
+            // objects at ANY depth (top-level Object3D fields AND nested model
+            // arrays like trackedImages[i].object) BEFORE deserialization — the
+            // typed serializers then do the wrapping (an AssetReference field
+            // wraps the node, an Object3D field takes it as is). The references
+            // map is complete here, so cross-reference wiring works regardless
+            // of load order. Copy-on-write: the document is never mutated.
+            const cleanData = resolveNodeReferencesDeep(compData, root, references, issue) as { name: string; guid?: string } & Record<string, unknown>;
+            if (serializationContext.applyComponent) serializationContext.applyComponent(obj, cleanData, issue);
+            else issue("def", `unsupported component type "${compData.name}"`);
+        }
+    }
+}
+
+/**
+ * Deep-resolve NODE-REFERENCE values (`{ref: <known reference id>, address?}`) in def
+ * component data to the LIVE scene objects. Values whose `ref` is not a known
+ * reference id stay untouched for the regular serializers (entity refs, arbitrary
+ * objects). Unresolvable references become undefined (reported as an issue) — never
+ * a raw `{ref}` object leaking into a component field.
+ */
+function resolveNodeReferencesDeep(value: unknown, root: Object3D, references: Map<string, Object3D>, issue: (arc: "def", message: string) => void): unknown {
+    if (!value || typeof value !== "object") return value;
+    if (Array.isArray(value)) {
+        let copy: unknown[] | null = null;
+        for (let i = 0; i < value.length; i++) {
+            const resolved = resolveNodeReferencesDeep(value[i], root, references, issue);
+            if (resolved !== value[i]) {
+                if (!copy) copy = [...value];
+                copy[i] = resolved;
+            }
+        }
+        return copy ?? value;
+    }
+    const candidate = value as { ref?: unknown };
+    if (typeof candidate.ref === "string" && references.has(candidate.ref)) {
+        const resolved = resolveTargetObject(value as ProjectDocumentTarget, root, references);
+        if (!resolved) {
+            issue("def", `node reference did not resolve: ${JSON.stringify(value)}`);
+            return undefined;
+        }
+        return resolved;
+    }
+    let copy: Record<string, unknown> | null = null;
+    for (const [key, entry] of Object.entries(value)) {
+        const resolved = resolveNodeReferencesDeep(entry, root, references, issue);
+        if (resolved !== entry) {
+            if (!copy) copy = { ...(value as Record<string, unknown>) };
+            copy[key] = resolved;
+        }
+    }
+    return copy ?? value;
+}
+
+// ---------------------------------------------------------------------------
+// overs
+// ---------------------------------------------------------------------------
+
+async function applyOvers(context: Context, document: ProjectDocument, root: Object3D, references: Map<string, Object3D>, entities: Map<string, Promise<object | null>>, issue: (arc: "over", message: string) => void, sceneTargets: ReadonlyMap<ProjectDocumentTarget, Object3D | null>): Promise<void> {
+    const state = createOverApplyState(entities);
+    state.sceneTargets = sceneTargets;
+    for (const over of document.overs ?? []) {
+        applyOver(context, over, root, references, state, issue);
+    }
+    await state.settled();
+}
+
+/**
+ * The shared state a sequence of over applications rides — constructed once per
+ * document evaluation AND once per op-bridge apply session (the applicator,
+ * plans/operation-bridge.md fixture 2):
+ * - async entity chaining: entity-targeted overs and entity-ref values await the
+ *   entity's instantiation; overs touching the same entity keep their order among
+ *   themselves by chaining on the entity's tail promise. Non-async overs apply
+ *   synchronously (pre-awake); `settled()` awaits the async remainder.
+ * - deactivated subtrees ("active": false → removeFromParent), per scope ref:
+ *   materials are RESOURCES, not graph nodes — a material used only by a
+ *   deactivated mesh must stay addressable (doc order legally deactivates first
+ *   and patches after), so material resolution searches these detached roots too.
+ */
+export type OverApplyState = {
+    /** Bind original-scene addresses before any rename, removal or reparent changes their paths. */
+    sceneTargets?: ReadonlyMap<ProjectDocumentTarget, Object3D | null>;
+    readonly entities: Map<string, Promise<object | null>>;
+    readonly deactivatedRoots: Map<string | undefined, Object3D[]>;
+    chainOnEntity(refId: string, work: (entity: object | null) => void): void;
+    settled(): Promise<void>;
+};
+
+export function createOverApplyState(entities: Map<string, Promise<object | null>>): OverApplyState {
+    const pending: Promise<void>[] = [];
+    const entityTails = new Map<string, Promise<void>>();
+    const deactivatedRoots = new Map<string | undefined, Object3D[]>();
+    return {
+        entities,
+        deactivatedRoots,
+        chainOnEntity(refId: string, work: (entity: object | null) => void): void {
+            const instantiation = entities.get(refId)!;
+            const prev = entityTails.get(refId) ?? Promise.resolve();
+            const tail = Promise.all([instantiation, prev]).then(([entity]) => work(entity));
+            entityTails.set(refId, tail);
+            pending.push(tail);
+        },
+        settled: () => Promise.all(pending).then(() => undefined),
+    };
+}
+
+/**
+ * Apply ONE over to the live composition — the single-arc primitive: document
+ * evaluation loops over it, and the op-bridge APPLICATOR applies a remote
+ * property/assign/deactivation op through exactly this function (one
+ * implementation, plans/operation-bridge.md fixture 2).
+ */
+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 {
+    const { entities, deactivatedRoots, chainOnEntity } = state;
+    {
+        const target = over?.target;
+        if (!target || typeof target.path !== "string" || target.path.length === 0) {
+            issue("over", `over without a target path: ${JSON.stringify(over)}`);
+            return;
+        }
+        // "parent" is a reserved STRUCTURAL path — applied in the placement phase
+        // (after all placements, index-ordered), never as a property write
+        if (target.path === "parent") return;
+
+        // ---- ENTITY-targeted over: patch the pooled entity itself ----------------
+        if (target.ref !== undefined && entities.has(target.ref)) {
+            const refId = target.ref, path = target.path, value = over.value, tgt = target;
+            chainOnEntity(refId, entity => {
+                if (!entity) return; // instantiation failure already reported
+                applyValueAtPath(context, entity, path, value, issue, tgt);
+            });
+            return;
+        }
+
+        // materials resolve against the scope's meshes, everything else via the graph
+        let element: object | null = null;
+        let owner: Object3D | null = null;
+        if (target.ref === "$scene") {
+            // reserved ref: the CONTEXT SCENE — scene-level opinions (background,
+            // environment, fog) apply to the scene itself, NOT the composition parent
+            // (which is a plain container when the evaluator runs with a `parent`).
+            // With an ADDRESS, the target is a node INSIDE the scene (e.g. the engine's
+            // own camera — the start-camera pose overs). `$`-prefix is reserved.
+            element = state.sceneTargets?.has(target) ? state.sceneTargets.get(target) ?? null : target.address
+                ? resolveInGraph(target.address, context.scene as unknown as GraphNode) as unknown as object | null
+                : context.scene as unknown as object;
+        }
+        else if (target.ref === "$renderer") {
+            // reserved ref: the CONTEXT RENDERER — renderer-level opinions
+            // (toneMapping, toneMappingExposure). Addresses make no sense here.
+            if (target.address) {
+                issue("over", `"$renderer" targets take no address: ${JSON.stringify(target)}`);
+                return;
+            }
+            element = context.renderer as unknown as object;
+        }
+        else if (target.address?.type === "material") {
+            const scope = target.ref !== undefined ? references.get(target.ref) : root;
+            element = scope ? resolveTargetMaterial(scope, target.address, deactivatedRoots.get(target.ref))?.material ?? null : null;
+        }
+        else {
+            owner = state.sceneTargets?.has(target) ? state.sceneTargets.get(target) ?? null : resolveTargetObject(target, root, references);
+            element = owner;
+        }
+        if (!element) {
+            issue("over", `over target did not resolve: ${JSON.stringify(target)}`);
+            return;
+        }
+
+        // reserved LAST segment: "active" — deactivation (USD semantics: opinions on
+        // content the document does not own; false removes it from the composed result).
+        // Whatever the rest of the path resolved to is what gets deactivated, so a node
+        // ("active") and a component ("components/guid:…/active") share one mechanism.
+        const segments = splitPath(target.path);
+        if (segments[segments.length - 1] === "active") {
+            if (over.value !== false) return;
+            const holder = segments.length === 1
+                ? element
+                : walkPath(context, element, segments, target.ref, message => issue("over", `path "${target.path}" ${message}: ${JSON.stringify(target)}`))?.container;
+            if (holder) {
+                // remember detached subtrees so their material RESOURCES stay addressable
+                if ((holder as Object3D).isObject3D) {
+                    const detached = deactivatedRoots.get(target.ref) ?? [];
+                    detached.push(holder as Object3D);
+                    deactivatedRoots.set(target.ref, detached);
+                }
+                deactivate(context, holder, owner, issue);
+            }
+            return;
+        }
+
+        // ---- NODE-ref value ({ref: <reference id>, address?}): an Object3D field
+        // assigned BY REFERENCE to a node of the composition (the wire form the
+        // editor writes for object slots). Checked before the entity branch —
+        // reference ids and entity ids are distinct pools.
+        if (isEntityRefValue(over.value) && (over.value.ref === "$scene" || references.has(over.value.ref))) {
+            const node = state.sceneTargets?.has(over.value) ? state.sceneTargets.get(over.value)
+                : resolveTargetObject(over.value as ProjectDocumentTarget, root, references, context.scene);
+            if (!node) {
+                issue("over", `node-reference value did not resolve: ${JSON.stringify(over.value)} for ${JSON.stringify(target)}`);
+                return;
+            }
+            applyValueAtPath(context, element, target.path, node, issue, target);
+            return;
+        }
+
+        // ---- ENTITY-ref value: assign the pooled entity (USD material:binding) ----
+        // NEVER raw-assign a reference object (that breaks the property).
+        if (isEntityRefValue(over.value)) {
+            const refId = over.value.ref;
+            const instantiation = entities.get(refId);
+            if (!instantiation) {
+                issue("over", `value references unknown entity "${refId}": ${JSON.stringify(target)}`);
+                return;
+            }
+            const el = element, path = target.path, tgt = target;
+            chainOnEntity(refId, entity => {
+                if (!entity) {
+                    issue("over", `entity "${refId}" was not instantiated — assignment skipped: ${JSON.stringify(tgt)}`);
+                    return;
+                }
+                applyValueAtPath(context, el, path, entity, issue, tgt);
+            });
+            return;
+        }
+        if (isReferenceValued(over.value)) {
+            issue("over", `reference-valued over not supported (skipped, not raw-assigned): ${JSON.stringify(target)}`);
+            return;
+        }
+
+        applyValueAtPath(context, element, target.path, over.value, issue, target);
+    }
+}
+
+/** an over VALUE pointing at a pooled entity reference: `{ ref: "<reference id>" }` */
+function isEntityRefValue(v: unknown): v is { ref: string } {
+    return !!v && typeof v === "object" && typeof (v as { ref?: unknown }).ref === "string";
+}
+
+/** an over VALUE that is a reference to another element (never raw-assign these) */
+function isReferenceValued(v: unknown): boolean {
+    if (!v || typeof v !== "object") return false;
+    const o = v as Record<string, unknown>;
+    return typeof o.asset === "string" || o.node !== undefined || typeof o.guid === "string";
+}
+
+/**
+ * Resolve one of an asset's materials by address, through the shared ladder.
+ *
+ * The single-material fallback is CALLER policy, not part of the ladder, and it is a
+ * HEURISTIC rather than a contract: library material assets happen to be glbs carrying
+ * one material today, but nothing stops one gaining more, so this must never be the
+ * primary path. It exists only so an entity reference still resolves when the recorded
+ * address has drifted. When the asset does carry several materials the fallback simply
+ * does not apply and the caller reports an unresolved entity — a visible miss, never a
+ * silent guess at which material was meant.
+ */
+function findMaterialInModel(model: Model, address: NeedleAddress): object | null {
+    const scene = (model as unknown as { scene?: Object3D }).scene;
+    if (!scene) return null;
+    const materials = collectMaterials(scene);
+    return resolveInCollection(address, materials) ?? (materials.length === 1 ? materials[0] : null);
+}
+
+/**
+ * Material entity resolution incl. MATERIAL-ONLY glbs (a promoted material
+ * library entry: materials but no scene/meshes). The loader never
+ * instantiates an unreferenced material, so a scene traversal finds nothing —
+ * pull the materials from the parser instead. Exported for tests.
+ */
+export async function resolveMaterialEntity(model: Model, address: NeedleAddress): Promise<object | null> {
+    const found = findMaterialInModel(model, address);
+    if (found) return found;
+    const parser = (model as unknown as { parser?: { json?: { materials?: unknown[] }; getDependency?(type: string, index: number): Promise<unknown> } }).parser;
+    const count = parser?.json?.materials?.length ?? 0;
+    if (!count || !parser?.getDependency) return null;
+    const loaded: MaterialElement[] = [];
+    for (let i = 0; i < count; i++) {
+        const material = await parser.getDependency("material", i).catch(() => null);
+        if (material && typeof material === "object") loaded.push(material as MaterialElement);
+    }
+    return resolveInCollection(address, loaded) ?? (loaded.length === 1 ? loaded[0] : null);
+}
+
+/** drain a response body into one buffer, reporting cumulative received bytes per chunk */
+async function readBodyWithProgress(body: ReadableStream<Uint8Array>, onChunk: (receivedBytes: number) => void): Promise<ArrayBuffer> {
+    const reader = body.getReader();
+    const chunks: Uint8Array[] = [];
+    let received = 0;
+    for (; ;) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        if (value) {
+            chunks.push(value);
+            received += value.byteLength;
+            onChunk(received);
+        }
+    }
+    const result = new Uint8Array(received);
+    let offset = 0;
+    for (const chunk of chunks) {
+        result.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return result.buffer;
+}
+
+function deactivate(context: Context, element: object, owner: Object3D | null, issue: (arc: "over", message: string) => void) {
+    if ((element as Object3D).isObject3D) {
+        (element as Object3D).removeFromParent();
+    }
+    else if (context.removeComponent) context.removeComponent(element, owner);
+    else issue("over", "component deactivation is not supported by this host");
+}
+
+function applyValueAtPath(context: Context, element: object, path: string, value: unknown, issue: (arc: "over", message: string) => void, target: ProjectDocumentTarget) {
+    const segments = splitPath(path);
+    // the walked chain — materials/textures along it need `needsUpdate` after a set
+    // (deep overs like "material/map/repeat" patch texture state that three only
+    // uploads/recompiles when flagged)
+    const walked = walkPath(context, element, segments, target.ref, message => issue("over", `path "${path}" ${message}: ${JSON.stringify(target)}`));
+    if (!walked) return;
+    const { container, chain } = walked;
+    const current = container as Record<string, unknown>;
+    const key = segments[segments.length - 1];
+    const existing = current[key];
+    // three.js value types (Vector3, Color, Quaternion, …) are patched in place from
+    // arrays; primitives and everything else assign directly
+    if (Array.isArray(value) && existing && typeof existing === "object" && typeof (existing as { fromArray?: unknown }).fromArray === "function") {
+        (existing as { fromArray(v: unknown[]): void }).fromArray(value);
+    }
+    else if (Array.isArray(value) && value.length === 3 && key === "background" && (current as { isScene?: boolean }).isScene === true) {
+        // scene.background is null OR a texture (environment) by default — a color over
+        // must CONSTRUCT/REPLACE with a Color (raw-assigning the array breaks rendering;
+        // the generic fromArray branch above already handled an existing Color)
+        current[key] = context.createColor(value as number[]);
+    }
+    else {
+        current[key] = value;
+    }
+    for (const touched of chain) {
+        const o = touched as { isMaterial?: boolean; isTexture?: boolean; needsUpdate?: boolean };
+        if (o.isMaterial === true || o.isTexture === true) o.needsUpdate = true;
+    }
+}