@needle-tools/addressing 0.3.3 → 0.3.4

package/dist/target.js

@@ -0,0 +1,112 @@
+// the six characters the grammar reserves (+ "%" as the escape lead) — encoded
+// with %xx so decodeURIComponent inverts; everything else stays raw and human-
+// readable ("$scene" must print as "$scene", not "%24scene")
+function encodeToken(value) {
+    return value
+        .replace(/%/g, "%25")
+        .replace(/\//g, "%2F")
+        .replace(/:/g, "%3A")
+        .replace(/#/g, "%23")
+        .replace(/~/g, "%7E")
+        .replace(/!/g, "%21")
+        .replace(/@/g, "%40");
+}
+function decodeToken(value) {
+    try {
+        return decodeURIComponent(value);
+    }
+    catch {
+        return null; // a lone "%" — not a token we printed
+    }
+}
+/** print a target as its canonical token — null when there is nothing to name */
+export function targetToString(target) {
+    const address = target.address;
+    const hasAddress = !!address && (address.id !== undefined || address.anchor !== undefined || address.name !== undefined || address.path !== undefined || address.type !== undefined);
+    if (!target.ref && !hasAddress)
+        return null;
+    let token = `@${target.ref ? encodeToken(target.ref) : ""}`;
+    if (hasAddress) {
+        token += "/";
+        const type = address.type ?? "node";
+        if (type !== "node")
+            token += `${encodeToken(type)}:`;
+        if (address.id !== undefined)
+            token += encodeToken(address.id);
+        if (address.anchor !== undefined)
+            token += `#${encodeToken(address.anchor)}`;
+        if (address.name !== undefined)
+            token += `~${encodeToken(address.name)}`;
+        if (address.path !== undefined)
+            token += `!${address.path}`;
+    }
+    return token;
+}
+/** parse a canonical token back to the target — null for anything this module
+ * did not print (retired grammars, garbage): a loud miss, never a half-parse */
+export function targetFromString(token) {
+    if (typeof token !== "string" || !token.startsWith("@") || token.length < 2)
+        return null;
+    const body = token.slice(1);
+    const slash = body.indexOf("/");
+    const refRaw = slash === -1 ? body : body.slice(0, slash);
+    const addrRaw = slash === -1 ? undefined : body.slice(slash + 1);
+    const ref = refRaw.length > 0 ? decodeToken(refRaw) : undefined;
+    if (refRaw.length > 0 && ref === null)
+        return null;
+    if (addrRaw === undefined || addrRaw.length === 0) {
+        return ref ? { ref } : null;
+    }
+    // consume rungs back to front: path (verbatim remainder), name, anchor
+    let rest = addrRaw;
+    let path;
+    const bang = rest.indexOf("!");
+    if (bang !== -1) {
+        path = rest.slice(bang + 1);
+        rest = rest.slice(0, bang);
+    }
+    let name;
+    const tilde = rest.indexOf("~");
+    if (tilde !== -1) {
+        const decoded = decodeToken(rest.slice(tilde + 1));
+        if (decoded === null)
+            return null;
+        name = decoded;
+        rest = rest.slice(0, tilde);
+    }
+    let anchor;
+    const hash = rest.indexOf("#");
+    if (hash !== -1) {
+        const decoded = decodeToken(rest.slice(hash + 1));
+        if (decoded === null)
+            return null;
+        anchor = decoded;
+        rest = rest.slice(0, hash);
+    }
+    let type = "node";
+    const colon = rest.indexOf(":");
+    if (colon !== -1) {
+        const decoded = decodeToken(rest.slice(0, colon));
+        if (decoded === null || decoded.length === 0)
+            return null;
+        type = decoded;
+        rest = rest.slice(colon + 1);
+    }
+    let id;
+    if (rest.length > 0) {
+        const decoded = decodeToken(rest);
+        if (decoded === null)
+            return null;
+        id = decoded;
+    }
+    const address = { type };
+    if (id !== undefined)
+        address.id = id;
+    if (anchor !== undefined)
+        address.anchor = anchor;
+    if (name !== undefined)
+        address.name = name;
+    if (path !== undefined)
+        address.path = path;
+    return ref ? { ref, address } : { address };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@needle-tools/addressing",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "description": "Persistent addressing for Needle assets: deterministic needle-id computation, #needle anchors, and address resolution over glTF JSON and live scene graphs.",
   "type": "module",
   "main": "./src/index.ts",

package/src/address.ts

@@ -1,12 +1,13 @@
 import { parseAnchorValue } from "./anchor.js";
-import { getElementId, NEEDLE_ID_KEY, type GltfJson, type StampedElementType } from "./gltf.js";
+import { getElementId, NEEDLE_ID_KEY } from "./id.js";
+import { type GltfJson, type StampedElementType } from "./gltf.js";
 
 /**
  * A persistent pointer to an element inside an asset — the "fat address": every
  * fallback the resolver may need is captured at CREATION time, while the target is
  * known, instead of being reconstructed later.
  *
- * Resolution order: `id` (exact) → `anchor` (survives asset updates) → `namePath`
+ * Resolution order: `id` (exact) → `anchor` (survives asset updates) → `path`
  * (best-effort) → reconciliation (candidates + confidence, never a silent guess).
  */
 export type NeedleAddress = {
@@ -18,10 +19,42 @@ export type NeedleAddress = {
     type?: StampedElementType | (string & {});
     /** the target's name at address-creation time */
     name?: string;
-    /** node names from the asset root (exclusive) down to the target (inclusive); nodes only */
-    namePath?: string[];
+    /**
+     * Node names from the asset root (exclusive) down to the target (inclusive);
+     * nodes only. ONE path syntax everywhere (2026-08-03): `/`-separated segments
+     * with JSON-Pointer escaping (`~0` = `~`, `~1` = `/`) — see {@link joinPath} /
+     * {@link splitPath}. Empty SEGMENTS are load-bearing (positional walk over
+     * unnamed nodes), so `""` is a valid one-segment path — test `!== undefined`,
+     * never truthiness. ABSENT means "no path rung".
+     */
+    path?: string;
 };
 
+// #region path segment syntax
+// The one path syntax of the project format (target.path uses the same rules):
+// "/" separates segments; a literal "~" in a name is written "~0", a literal "/"
+// is written "~1" (JSON-Pointer, RFC 6901). Escape order matters on decode.
+
+/** escape one segment for embedding in a path string */
+export function encodePathSegment(name: string): string {
+    return name.replace(/~/g, "~0").replace(/\//g, "~1");
+}
+
+/** decode one path segment back to the literal name */
+export function decodePathSegment(segment: string): string {
+    return segment.replace(/~1/g, "/").replace(/~0/g, "~");
+}
+
+/** join literal segment names into an escaped path string */
+export function joinPath(segments: readonly string[]): string {
+    return segments.map(encodePathSegment).join("/");
+}
+
+/** split an escaped path string into literal segment names ("" → one empty segment) */
+export function splitPath(path: string): string[] {
+    return path.split("/").map(decodePathSegment);
+}
+
 /** Structural (duck-typed) view of a live scene-graph node — works with any three.js. */
 export type GraphNode = {
     name?: string;
@@ -29,7 +62,7 @@ export type GraphNode = {
     userData?: Record<string, unknown>;
 };
 
-/** Build an address for a glTF root-collection element. `namePath` only applies to nodes. */
+/** Build an address for a glTF root-collection element. `path` only applies to nodes. */
 export function createGltfElementAddress(json: GltfJson, type: StampedElementType | string, index: number): NeedleAddress | null {
     const collection = json[collectionKeyForType(type)];
     if (!Array.isArray(collection)) return null;
@@ -43,30 +76,30 @@ export function createGltfElementAddress(json: GltfJson, type: StampedElementTyp
     const anchor = parseAnchorValue(name);
     if (anchor) address.anchor = anchor;
     // an empty name is non-information: resolution never reads `name` (id → anchor →
-    // namePath) and reconciliation falls back to the last namePath segment ("" again).
-    // NOTE: empty namePath SEGMENTS are load-bearing (positional child-walk) — only the
+    // path) and reconciliation falls back to the last path segment ("" again).
+    // NOTE: empty path SEGMENTS are load-bearing (positional child-walk) — only the
     // standalone `name` field is dropped when empty.
     if (name) address.name = name;
     if (type === "node") {
-        const path = gltfNodeNamePath(json, index);
-        if (path) address.namePath = path;
+        const segments = gltfNodeNamePath(json, index);
+        if (segments) address.path = joinPath(segments);
     }
     return address;
 }
 
 /** Build an address for a live scene-graph object under `root`. */
 export function createObjectAddress(root: GraphNode, target: GraphNode): NeedleAddress | null {
-    const path = findPath(root, target);
-    if (!path) return null;
+    const nodes = findPath(root, target);
+    if (!nodes || nodes.length === 0) return null; // the root itself has no path — address it by ref alone
 
     const address: NeedleAddress = { type: "node" };
     const id = target.userData?.[NEEDLE_ID_KEY];
     if (typeof id === "string") address.id = id;
     const anchor = parseAnchorValue(target.name);
     if (anchor) address.anchor = anchor;
-    // empty name dropped — see createGltfElementAddress; namePath segments stay verbatim
+    // empty name dropped — see createGltfElementAddress; path segments stay verbatim
     if (target.name) address.name = target.name;
-    address.namePath = path.map(n => n.name ?? "");
+    address.path = joinPath(nodes.map(n => n.name ?? ""));
     return address;
 }
 

package/src/gltf.ts

@@ -1,7 +1,8 @@
-import { computeElementId, idNameOf } from "./id.js";
-
-/** The glTF `extras` key carrying the persistent id. */
-export const NEEDLE_ID_KEY = "needle-id";
+/**
+ * Structural glTF shapes — the duck-typed views of a glTF JSON root and its
+ * elements, plus which collections carry ids. All id READING and MINTING lives
+ * in `id.ts`; this module only describes the file format.
+ */
 
 /** All root-collection element types that receive ids, with their glTF collection key. */
 export const STAMPED_COLLECTIONS = [
@@ -30,62 +31,3 @@ export type GltfElement = {
 export type GltfJson = {
     [collection: string]: unknown;
 };
-
-export type EnsureIdsOptions = {
-    /**
-     * Optional salt scoping unanchored ids to an external identity (e.g. an
-     * asset/content id). By default no salt is used — ids derive from the element alone
-     * (type, name, occurrence-of-name), so any tool mints the same ids with no
-     * coordination. With a salt, only writers that know it agree — safe because
-     * existing ids are never overwritten (whoever stamps first wins).
-     */
-    baseHash?: string;
-};
-
-export type EnsureIdsResult = {
-    /** the salt the ids were derived with, when one was provided */
-    baseHash?: string;
-    /** how many elements received a new id (0 → the file was already fully stamped) */
-    assigned: number;
-};
-
-/**
- * Idempotently inject `extras["needle-id"]` into every element of the stamped
- * collections. Existing ids are never overwritten, so already-stamped files pass
- * through unchanged and every id writer agrees with whoever stamped first.
- *
- * Mutates `json` in place.
- */
-export function ensureIds(json: GltfJson, options?: EnsureIdsOptions): EnsureIdsResult {
-    const baseHash = options?.baseHash;
-    let assigned = 0;
-    for (const [type, collection] of STAMPED_COLLECTIONS) {
-        const elements = json[collection];
-        if (!Array.isArray(elements)) continue;
-        // occurrence-of-name: the id input is the element's position among same-named
-        // elements, NOT its collection index — uniquely named elements keep their ids
-        // across reorders and asset updates. Grouping is by the DERIVATION name
-        // (anchor marker stripped, normalized), matching occurrenceOfName.
-        const occurrences = new Map<string, number>();
-        for (let index = 0; index < elements.length; index++) {
-            const element = elements[index] as GltfElement;
-            if (element == null || typeof element !== "object") continue;
-            const name = typeof element.name === "string" ? element.name : "";
-            const group = idNameOf(name);
-            const occurrence = occurrences.get(group) ?? 0;
-            occurrences.set(group, occurrence + 1);
-            element.extras ??= {};
-            if (element.extras[NEEDLE_ID_KEY] === undefined) {
-                element.extras[NEEDLE_ID_KEY] = computeElementId(type, name, occurrence, baseHash);
-                assigned++;
-            }
-        }
-    }
-    return { baseHash, assigned };
-}
-
-/** Read an element's needle-id without computing anything. */
-export function getElementId(element: GltfElement | null | undefined): string | null {
-    const id = element?.extras?.[NEEDLE_ID_KEY];
-    return typeof id === "string" ? id : null;
-}

package/src/id.ts

@@ -1,5 +1,20 @@
 import { normalizeName, parseAnchor } from "./anchor.js";
-import { uuidv5 } from "./uuid.js";
+import { STAMPED_COLLECTIONS, type GltfElement, type GltfJson } from "./gltf.js";
+import { randomUuid, uuidv5 } from "./uuid.js";
+import type { GraphNode } from "./address.js";
+
+/**
+ * THE identity module: every read and every mint of a needle-id lives here —
+ * derivation (deterministic ids for glTF elements), glTF stamping/readback
+ * (`extras`), and live-node stamping/readback (`userData`). Consumers never
+ * touch the key or mint ids themselves.
+ */
+
+/** The key carrying the persistent id — glTF `extras` for file elements, live
+ * `userData` for scene objects (exports copy one into the other). */
+export const NEEDLE_ID_KEY = "needle-id";
+
+// #region Derivation
 
 /**
  * The name an id is derived FROM: the anchor marker removed (if any) and space/underscore
@@ -59,3 +74,128 @@ export function occurrenceOfName(elements: ReadonlyArray<{ name?: unknown } | nu
     }
     return occurrence;
 }
+
+// #endregion
+
+// #region glTF elements (extras)
+
+export type EnsureIdsOptions = {
+    /**
+     * Optional salt scoping unanchored ids to an external identity (e.g. an
+     * asset/content id). By default no salt is used — ids derive from the element alone
+     * (type, name, occurrence-of-name), so any tool mints the same ids with no
+     * coordination. With a salt, only writers that know it agree — safe because
+     * existing ids are never overwritten (whoever stamps first wins).
+     */
+    baseHash?: string;
+};
+
+export type EnsureIdsResult = {
+    /** the salt the ids were derived with, when one was provided */
+    baseHash?: string;
+    /** how many elements received a new id (0 → the file was already fully stamped) */
+    assigned: number;
+};
+
+/**
+ * Idempotently inject `extras["needle-id"]` into every element of the stamped
+ * collections. Existing ids are never overwritten, so already-stamped files pass
+ * through unchanged and every id writer agrees with whoever stamped first.
+ *
+ * Mutates `json` in place.
+ */
+export function ensureIds(json: GltfJson, options?: EnsureIdsOptions): EnsureIdsResult {
+    const baseHash = options?.baseHash;
+    let assigned = 0;
+    for (const [type, collection] of STAMPED_COLLECTIONS) {
+        const elements = json[collection];
+        if (!Array.isArray(elements)) continue;
+        // occurrence-of-name: the id input is the element's position among same-named
+        // elements, NOT its collection index — uniquely named elements keep their ids
+        // across reorders and asset updates. Grouping is by the DERIVATION name
+        // (anchor marker stripped, normalized), matching occurrenceOfName.
+        const occurrences = new Map<string, number>();
+        for (let index = 0; index < elements.length; index++) {
+            const element = elements[index] as GltfElement;
+            if (element == null || typeof element !== "object") continue;
+            const name = typeof element.name === "string" ? element.name : "";
+            const group = idNameOf(name);
+            const occurrence = occurrences.get(group) ?? 0;
+            occurrences.set(group, occurrence + 1);
+            element.extras ??= {};
+            if (element.extras[NEEDLE_ID_KEY] === undefined) {
+                element.extras[NEEDLE_ID_KEY] = computeElementId(type, name, occurrence, baseHash);
+                assigned++;
+            }
+        }
+    }
+    return { baseHash, assigned };
+}
+
+/** Read an element's needle-id without computing anything. */
+export function getElementId(element: GltfElement | null | undefined): string | null {
+    const id = element?.extras?.[NEEDLE_ID_KEY];
+    return typeof id === "string" ? id : null;
+}
+
+// #endregion
+
+// #region Live nodes (userData)
+
+/** Read a live node's needle-id from `userData` — the live-object counterpart of
+ * {@link getElementId}, which reads glTF `extras`. */
+export function getNodeId(target: GraphNode | null | undefined): string | null {
+    const id = target?.userData?.[NEEDLE_ID_KEY];
+    return typeof id === "string" ? id : null;
+}
+
+/** Ensure a live node carries a needle-id: returns the existing one or MINTS a
+ * random uuid into `userData`. Random by design — editor-created (scratch) content
+ * has no derivation basis; the id persists because exports write `userData` ids
+ * into glTF `extras` (create → save → reload sees the same id). */
+export function ensureNodeId(target: GraphNode): string {
+    const userData = (target.userData ??= {});
+    const existing = userData[NEEDLE_ID_KEY];
+    if (typeof existing === "string") return existing;
+    const id = randomUuid();
+    userData[NEEDLE_ID_KEY] = id;
+    return id;
+}
+
+export type ShedIdentityOptions = {
+    /** additional identity keys deleted from every `userData.components` entry —
+     * the caller names its component-identity keys (e.g. an engine's editor-guid
+     * key); addressing owns the traversal and the needle-id rule */
+    componentKeys?: readonly string[];
+};
+
+/**
+ * Shed a subtree's AUTHORED identity — for clones (duplicate/paste) before they are
+ * re-stamped. Stamped needle-ids are deleted on every node: sibling id collisions
+ * break addressing (an id-addressed edit resolves to whichever holder comes first).
+ * With `componentKeys`, the same keys are deleted from `userData.components`
+ * entries (a copied component guid would bake the ORIGINAL's identity into the
+ * clone's next export). Fresh ids are minted by whatever stamps next.
+ */
+export function shedNodeIdentity(root: GraphNode, options?: ShedIdentityOptions): void {
+    const componentKeys = options?.componentKeys ?? [];
+    const visit = (node: GraphNode): void => {
+        const userData = node.userData;
+        if (userData) {
+            if (typeof userData[NEEDLE_ID_KEY] === "string") delete userData[NEEDLE_ID_KEY];
+            const components = userData["components"];
+            if (Array.isArray(components)) {
+                for (const component of components) {
+                    if (!component || typeof component !== "object") continue;
+                    for (const key of componentKeys) {
+                        if ((component as Record<string, unknown>)[key] !== undefined) delete (component as Record<string, unknown>)[key];
+                    }
+                }
+            }
+        }
+        for (const child of node.children ?? []) visit(child);
+    };
+    visit(root);
+}
+
+// #endregion

package/src/index.ts

@@ -1,12 +1,19 @@
 export { ANCHOR_MARKER, ANCHOR_MARKERS, parseAnchor, parseAnchorValue, type ParsedAnchor } from "./anchor.js";
-export { computeElementId, occurrenceOfName } from "./id.js";
 export {
+    computeElementId,
     ensureIds,
+    ensureNodeId,
     getElementId,
+    getNodeId,
     NEEDLE_ID_KEY,
-    STAMPED_COLLECTIONS,
+    occurrenceOfName,
+    shedNodeIdentity,
     type EnsureIdsOptions,
     type EnsureIdsResult,
+    type ShedIdentityOptions,
+} from "./id.js";
+export {
+    STAMPED_COLLECTIONS,
     type GltfElement,
     type GltfJson,
     type StampedElementType,
@@ -15,7 +22,11 @@ export {
     collectionKeyForType,
     createGltfElementAddress,
     createObjectAddress,
+    decodePathSegment,
+    encodePathSegment,
     findPath,
+    joinPath,
+    splitPath,
     type GraphNode,
     type NeedleAddress,
 } from "./address.js";
@@ -31,4 +42,5 @@ export {
     type ResolutionRung,
     type ResolveOptions,
 } from "./resolve.js";
+export { targetFromString, targetToString, type AddressTarget } from "./target.js";
 export { randomUuid, uuidv5, UUID_NAMESPACE_URL } from "./uuid.js";

package/src/resolve.ts

@@ -1,6 +1,7 @@
 import { parseAnchorValue } from "./anchor.js";
-import { collectionKeyForType, type GraphNode, type NeedleAddress } from "./address.js";
-import { NEEDLE_ID_KEY, STAMPED_COLLECTIONS, type GltfJson } from "./gltf.js";
+import { collectionKeyForType, splitPath, type GraphNode, type NeedleAddress } from "./address.js";
+import { NEEDLE_ID_KEY } from "./id.js";
+import { STAMPED_COLLECTIONS, type GltfJson } from "./gltf.js";
 
 export type GltfResolveResult = {
     type: string;
@@ -10,7 +11,7 @@ export type GltfResolveResult = {
 
 /**
  * Resolve an address inside glTF JSON. Same ladder as the live graph —
- * **anchor → id → namePath** (nodes) — with the anchor winning only when it matches
+ * **anchor → id → path** (nodes) — with the anchor winning only when it matches
  * exactly one element. Returns null when nothing matches exactly (reconciliation is a
  * separate, explicit step — resolution never guesses).
  */
@@ -51,8 +52,8 @@ export function resolveInGltf(address: NeedleAddress, json: GltfJson, options?:
     }
     if (byId) return byId;
 
-    if (address.namePath?.length && (!address.type || address.type === "node")) {
-        const index = walkGltfNamePath(json, address.namePath);
+    if (address.path !== undefined && (!address.type || address.type === "node")) {
+        const index = walkGltfNamePath(json, splitPath(address.path));
         if (index !== null) {
             const nodes = json["nodes"] as Array<Record<string, unknown>>;
             return { type: "node", index, element: nodes[index] };
@@ -62,7 +63,7 @@ export function resolveInGltf(address: NeedleAddress, json: GltfJson, options?:
 }
 
 /** which rung of the ladder produced (or could have produced) a match */
-export type ResolutionRung = "id" | "anchor" | "namePath" | "name";
+export type ResolutionRung = "id" | "anchor" | "path" | "name";
 
 /**
  * Something a caller may want to show a human. Never an error — resolution still returns
@@ -90,7 +91,7 @@ export type ResolveOptions = {
 /**
  * Resolve an address inside a live scene graph (duck-typed — any three.js).
  *
- * Ladder: **anchor → id → namePath**. The anchor comes first because it is a deliberate,
+ * Ladder: **anchor → id → path**. The anchor comes first because it is a deliberate,
  * human-authored declaration, while an id may be a derived value whose basis shifted when
  * the content changed. It only wins when it resolves UNIQUELY: anchors are labels and may
  * legally repeat, and an ambiguous label must never outrank an exact key.
@@ -118,9 +119,9 @@ export function resolveInGraph(address: NeedleAddress, root: GraphNode, options?
     }
     if (byId) return byId;
 
-    if (address.namePath?.length) {
+    if (address.path !== undefined) {
         let current: GraphNode | null = root;
-        for (const segment of address.namePath) {
+        for (const segment of splitPath(address.path)) {
             current = current.children?.find(c => (c.name ?? "") === segment) ?? null;
             if (!current) break;
         }
@@ -139,7 +140,7 @@ export type AddressableElement = {
  * Resolve an address against a FLAT collection of live elements — materials, textures and
  * anything else that carries a name and `userData` but is not part of the scene graph.
  *
- * Same ladder as the graph, minus `namePath` (there is no hierarchy to walk) plus `name`
+ * Same ladder as the graph, minus `path` (there is no hierarchy to walk) plus `name`
  * as the final rung, since a flat collection has no positional fallback. This exists so
  * every element type resolves through ONE implementation: materials previously had their
  * own ladders, could not be anchored at all, and disagreed with each other about whether a
@@ -182,19 +183,20 @@ export type ReconcileCandidate = {
 /**
  * When exact resolution fails (the asset changed), propose candidates instead of
  * guessing: nodes matching the address's name, ranked by how much of the recorded
- * namePath still matches. Callers decide thresholds and whether to re-anchor.
+ * path still matches. Callers decide thresholds and whether to re-anchor.
  */
 export function reconcileInGraph(address: NeedleAddress, root: GraphNode): ReconcileCandidate[] {
-    if (!address.name && !address.namePath?.length) return [];
-    const targetName = address.name ?? address.namePath![address.namePath!.length - 1];
+    const addressSegments = address.path !== undefined ? splitPath(address.path) : null;
+    if (!address.name && !addressSegments?.length) return [];
+    const targetName = address.name ?? addressSegments![addressSegments!.length - 1];
 
     const candidates: ReconcileCandidate[] = [];
-    collectDescendants(root, (node, namePath) => {
+    collectDescendants(root, (node, segments) => {
         if ((node.name ?? "") !== targetName) return;
         const reasons = [`name matches "${targetName}"`];
         let confidence = 0.5;
-        if (address.namePath?.length) {
-            const similarity = pathSuffixSimilarity(address.namePath, namePath);
+        if (addressSegments?.length) {
+            const similarity = pathSuffixSimilarity(addressSegments, segments);
             confidence += 0.4 * similarity;
             if (similarity > 0) reasons.push(`path suffix similarity ${(similarity * 100).toFixed(0)}%`);
         }
@@ -233,14 +235,14 @@ function findInCollection(json: GltfJson, key: string, predicate: (el: Record<st
     return null;
 }
 
-function walkGltfNamePath(json: GltfJson, namePath: string[]): number | null {
+function walkGltfNamePath(json: GltfJson, segments: string[]): number | null {
     const nodes = json["nodes"];
     const scenes = json["scenes"];
     if (!Array.isArray(nodes) || !Array.isArray(scenes)) return null;
     // roots: the union of all scenes' root nodes
     let candidates: number[] = scenes.flatMap(s => (Array.isArray(s?.nodes) ? s.nodes : []));
     let match: number | null = null;
-    for (const segment of namePath) {
+    for (const segment of segments) {
         match = candidates.find(i => ((nodes[i]?.name ?? "") === segment)) ?? null;
         if (match === null) return null;
         const children = nodes[match]?.children;
@@ -285,17 +287,17 @@ function findInGraph(root: GraphNode, predicate: (node: GraphNode) => boolean, v
 }
 
 /** visit every descendant of root with its root-exclusive name path (including own name) */
-function collectDescendants(root: GraphNode, visit: (node: GraphNode, namePath: string[]) => void): void {
+function collectDescendants(root: GraphNode, visit: (node: GraphNode, segments: string[]) => void): void {
     const visited = new Set<GraphNode>();
-    const walk = (node: GraphNode, namePath: string[]) => {
+    const walk = (node: GraphNode, segments: string[]) => {
         if (visited.has(node)) return;
         visited.add(node);
-        if (node !== root) visit(node, namePath);
+        if (node !== root) visit(node, segments);
         if (!node.children) return;
         for (let i = 0; i < node.children.length; i++) {
             const child = node.children[i];
             if (child == null) continue;
-            walk(child, [...namePath, child.name ?? ""]);
+            walk(child, [...segments, child.name ?? ""]);
         }
     };
     walk(root, []);