@needle-tools/addressing 0.3.4 → 0.4.0

package/src/loadedGltf.ts

@@ -0,0 +1,93 @@
+import { computeElementId, getElementId, NEEDLE_ID_KEY, occurrenceOfName } from "./id.js";
+import type { GltfElement } from "./gltf.js";
+
+/**
+ * Eager-compute half of the persistent-id contract:
+ * ids are computed at LOAD time against the pristine glTF JSON — the deterministic inputs
+ * (original names and their order) only exist pristinely then — and attached to the LIVE
+ * objects' userData. The source file is not touched; persistence happens on save, where
+ * the exporter writes userData back into extras.
+ *
+ * Already-stamped assets carry ids in extras (which the loader copies to userData); those
+ * are respected and always win over recomputation.
+ */
+
+/** subset of three GLTFLoader's `parser.associations` values that we consume */
+export type GltfAssociation = {
+	nodes?: number;
+	materials?: number;
+	textures?: number;
+	cameras?: number;
+};
+
+type UserDataHost = { userData?: Record<string, unknown> };
+
+/**
+ * association key → (glTF collection, element type) — in precedence order: the scene-graph
+ * identity (node) wins when one live object carries several associations (e.g. a Mesh
+ * created for a single-use glTF node). glTF `mesh` elements are deliberately NOT attached:
+ * they are shared data, and stamping a scene object with a mesh id would alias two
+ * identities (a mesh used by two nodes would give both objects the same id).
+ */
+const ASSOCIATION_MAPPING = [
+	["nodes", "node"],
+	["materials", "material"],
+	["textures", "texture"],
+	["cameras", "camera"],
+] as const;
+
+export type AttachNeedleIdsResult = {
+	/** how many live objects received an id (already-stamped userData is left untouched) */
+	attached: number;
+};
+
+/**
+ * Attach needle-ids to the live objects of a loaded glTF.
+ * @param json the PRISTINE parsed glTF JSON (as read from the file, before any mutation)
+ * @param associations three GLTFLoader `parser.associations` (live object → element indices)
+ * @param scenes loaded scene objects, ordered like `json.scenes`
+ */
+export function attachNeedleIdsToLoadedGltf(
+	json: Record<string, unknown>,
+	associations: ReadonlyMap<object, GltfAssociation | undefined> | null | undefined,
+	scenes?: readonly (UserDataHost | null | undefined)[] | null,
+): AttachNeedleIdsResult {
+	let attached = 0;
+
+	const attach = (target: UserDataHost, type: string, collection: string, index: number) => {
+		const userData = target.userData;
+		if (!userData || typeof userData !== "object") return;
+		if (typeof userData[NEEDLE_ID_KEY] === "string") return; // loader copied extras, or already attached
+		const elements = json[collection];
+		if (!Array.isArray(elements)) return;
+		const element = elements[index] as GltfElement | undefined;
+		if (!element || typeof element !== "object") return;
+		// occurrence-of-name (not index) is the id input — computed from the pristine
+		// collection so ids match what any other tool stamps for this file
+		const id = getElementId(element) ?? computeElementId(type, element.name, occurrenceOfName(elements, index));
+		userData[NEEDLE_ID_KEY] = id;
+		attached++;
+	};
+
+	if (associations) {
+		for (const [object, association] of associations) {
+			if (!association || typeof object !== "object") continue;
+			for (const [key, type] of ASSOCIATION_MAPPING) {
+				const index = association[key];
+				if (typeof index === "number") {
+					attach(object as UserDataHost, type, key, index);
+					break; // precedence: first matching association identifies the object
+				}
+			}
+		}
+	}
+
+	if (scenes) {
+		for (let i = 0; i < scenes.length; i++) {
+			const scene = scenes[i];
+			if (scene) attach(scene, "scene", "scenes", i);
+		}
+	}
+
+	return { attached };
+}

package/src/resolve.ts

@@ -1,5 +1,5 @@
 import { parseAnchorValue } from "./anchor.js";
-import { collectionKeyForType, splitPath, type GraphNode, type NeedleAddress } from "./address.js";
+import { collectionKeyForType, splitNodePath, type GraphNode, type NeedleAddress } from "./address.js";
 import { NEEDLE_ID_KEY } from "./id.js";
 import { STAMPED_COLLECTIONS, type GltfJson } from "./gltf.js";
 
@@ -53,7 +53,7 @@ export function resolveInGltf(address: NeedleAddress, json: GltfJson, options?:
     if (byId) return byId;
 
     if (address.path !== undefined && (!address.type || address.type === "node")) {
-        const index = walkGltfNamePath(json, splitPath(address.path));
+        const index = walkGltfNamePath(json, splitNodePath(address.path));
         if (index !== null) {
             const nodes = json["nodes"] as Array<Record<string, unknown>>;
             return { type: "node", index, element: nodes[index] };
@@ -121,8 +121,9 @@ export function resolveInGraph(address: NeedleAddress, root: GraphNode, options?
 
     if (address.path !== undefined) {
         let current: GraphNode | null = root;
-        for (const segment of splitPath(address.path)) {
-            current = current.children?.find(c => (c.name ?? "") === segment) ?? null;
+        for (const segment of splitNodePath(address.path)) {
+            const matches: GraphNode[] = current.children?.filter(c => (c.name ?? "") === segment.name) ?? [];
+            current = segment.occurrence !== undefined ? matches[segment.occurrence] ?? null : matches.length === 1 ? matches[0] : null;
             if (!current) break;
         }
         if (current && current !== root) return current;
@@ -186,7 +187,7 @@ export type ReconcileCandidate = {
  * path still matches. Callers decide thresholds and whether to re-anchor.
  */
 export function reconcileInGraph(address: NeedleAddress, root: GraphNode): ReconcileCandidate[] {
-    const addressSegments = address.path !== undefined ? splitPath(address.path) : null;
+    const addressSegments = address.path !== undefined ? splitNodePath(address.path).map(segment => segment.name) : null;
     if (!address.name && !addressSegments?.length) return [];
     const targetName = address.name ?? addressSegments![addressSegments!.length - 1];
 
@@ -235,7 +236,7 @@ function findInCollection(json: GltfJson, key: string, predicate: (el: Record<st
     return null;
 }
 
-function walkGltfNamePath(json: GltfJson, segments: string[]): number | null {
+function walkGltfNamePath(json: GltfJson, segments: Array<{ name: string; occurrence?: number }>): number | null {
     const nodes = json["nodes"];
     const scenes = json["scenes"];
     if (!Array.isArray(nodes) || !Array.isArray(scenes)) return null;
@@ -243,7 +244,8 @@ function walkGltfNamePath(json: GltfJson, segments: string[]): number | null {
     let candidates: number[] = scenes.flatMap(s => (Array.isArray(s?.nodes) ? s.nodes : []));
     let match: number | null = null;
     for (const segment of segments) {
-        match = candidates.find(i => ((nodes[i]?.name ?? "") === segment)) ?? null;
+        const matches = [...new Set(candidates)].filter(i => (nodes[i]?.name ?? "") === segment.name);
+        match = segment.occurrence !== undefined ? matches[segment.occurrence] ?? null : matches.length === 1 ? matches[0] : null;
         if (match === null) return null;
         const children = nodes[match]?.children;
         candidates = Array.isArray(children) ? children : [];