@needle-tools/addressing 0.3.4-1790936280.dramatic-tiramisu.86ca165 → 0.4.0

package/Readme.md

@@ -1,132 +1,132 @@
-# @needle-tools/addressing
-
-Persistent addressing for glTF assets and three.js scene graphs: deterministic
-`needle-id` computation, the `#needle` name-anchor scheme, and address resolution.
-
-Zero runtime dependencies, no three.js import (scene graphs are accessed structurally),
-usable in browsers, node, and workers.
-
-## Project documents
-
-`@needle-tools/addressing/document` exports the document types, evaluator,
-single-def/over application, optional inspection index, and schema validator.
-The JSON Schema is available at `@needle-tools/addressing/document/schema.json`.
-The document format is unchanged by this package split.
-
-The shared writer exports `writePropertyOver`, `captureDocumentValue`,
-`documentOverKey`, and `mergeDocumentOvers`. These encode property edits, retain
-addresses, remove net-undo edits, and merge saved overs. Hosts still supply node
-reference encoding, live-target checks, asset assembly, and component serialization.
-Non-finite numbers and unsupported values produce a writer issue instead of being
-silently changed by JSON serialization.
-
-`DocumentAssetAssembly` registers deduplicated asset sources and shared material
-or HDR entities in the writer's asset/reference tables. Material assignments reuse
-saved entity identities by source and material ID, even when asset keys change.
-Hosts supply the captured entity IDs and resolve asset ownership; the assembly
-contains no engine or editor dependencies.
-
-The evaluator accepts a `DocumentRuntime` host. It owns asset caching, reference
-placement, derived glTF IDs, target resolution, defs, property and parent overs,
-entity sharing, and issue reporting. The host supplies loading, object creation,
-cloning, and lifecycle scheduling. Needle Engine provides its own adapter;
-plain three.js can use the same evaluator:
-
-```ts
-import { Color, Object3D, Scene } from "three";
-import { GLTFLoader } from "three/examples/jsm/loaders/GLTFLoader.js";
-import { evaluateProjectDocument, type DocumentRuntime } from "@needle-tools/addressing/document";
-
-const scene = new Scene();
-const runtime: DocumentRuntime = {
-    scene,
-    renderer, // your existing renderer, for $renderer opinions
-    createNode: () => new Object3D(),
-    createColor: value => new Color().fromArray(value),
-    parse: (data, src) => new GLTFLoader().parseAsync(data, new URL(".", new URL(src, documentUrl)).href),
-    instantiate: node => (node as Object3D).clone(),
-    // Plain objects have no component lifecycle or template registrations.
-    parkTemplate() {},
-    activateInstance() {},
-    disposeTemplate() {},
-    schedule: work => work(),
-    loadEnvironment, // your existing HDR/PMREM loader: (url, options) => Promise<Texture | null>
-};
-const result = await evaluateProjectDocument(runtime, document, { baseUrl: documentUrl });
-await result.completed;
-```
-
-Supply `createDefContext` and the component access hooks if the host supports
-components. Without them, component defs are reported as unsupported; node defs
-and ordinary three.js properties still work. A skeletal or component-aware host
-must supply its matching clone implementation. The default addressing entry point
-does not import the document evaluator or any three.js runtime.
-
-## Ids
-
-Every glTF root-collection element (nodes, scenes, animations, cameras, materials,
-meshes, skins, textures, images, samplers) can carry a UUID in `extras["needle-id"]`:
-
-- **Anchored** — the element name ends with `#needle` (case-insensitive): the id derives
-  only from the text before the marker → it **survives any content change** as long as
-  the name stays. Spaces and underscores in the value are treated as equal (loaders
-  sanitize node names), so `Door Frame #needle` and `Door_Frame_#needle` share one id.
-- **Unanchored**: the id derives from the element's type, name, and its occurrence among
-  same-named elements → uniquely named elements keep their ids across reorders and
-  content updates; duplicates disambiguate by position within their name group; unnamed
-  elements are positional.
-
-`ensureIds(gltfJson)` stamps a parsed glTF idempotently — existing ids are never
-overwritten, and any tool stamping the same element mints the same id.
-
-`ensureIds(gltfJson, { baseHash })` optionally salts unanchored ids with a caller-supplied
-identity (e.g. a stable asset id), scoping them to that identity.
-
-## Addresses
-
-An address captures every fallback at creation time, while the target is known —
-`{ id, anchor?, type?, name?, path? }`. Resolution order is strict (path: "/"-separated segments, JSON-Pointer `~0`/`~1` escaping):
-
-1. `id` — exact match (`extras` in glTF JSON, `userData` in live scene graphs)
-2. `anchor` — survives asset updates
-3. `path` — best-effort structural match
-
-Node paths qualify same-named siblings with `~2n` (zero-based occurrence):
-`Cube~21` names the second `Cube`. Literal tildes remain escaped as `~0`.
-Unqualified ambiguous paths fail to resolve rather than picking the first child.
-These paths assume the original sibling order; use authored anchors or persistent
-IDs when the source scene changes.
-4. **reconciliation** — never automatic: `reconcileInGraph` returns ranked candidates
-   with confidence + reasons; the caller decides thresholds and whether to re-anchor.
-
-## API
-
-```ts
-import {
-    ensureIds, computeElementId, computeFileHash,         // write side
-    createGltfElementAddress, createObjectAddress,        // address records
-    resolveInGltf, resolveInGraph, reconcileInGraph,      // resolve side
-    parseAnchorValue, randomUuid, NEEDLE_ID_KEY,
-} from "@needle-tools/addressing";
-
-// stamp a parsed glTF (idempotent, never overwrites existing ids)
-const { fileHash, assigned } = ensureIds(gltfJson);
-
-// capture an address while the target is known
-const address = createObjectAddress(sceneRoot, targetObject);
-
-// later / elsewhere: resolve — or reconcile when the asset changed
-const hit = resolveInGraph(address, sceneRoot);
-const candidates = hit ? [] : reconcileInGraph(address, sceneRoot);
-```
-
-Out of scope by design: GLB container parsing (this package takes parsed JSON), file
-I/O, and any composition/override semantics.
-
-## Development
-
-```
-npm install
-npm test        # vitest — includes golden-fixture id tests
-npm run build   # tsc → dist/
-```
+# @needle-tools/addressing
+
+Persistent addressing for glTF assets and three.js scene graphs: deterministic
+`needle-id` computation, the `#needle` name-anchor scheme, and address resolution.
+
+Zero runtime dependencies, no three.js import (scene graphs are accessed structurally),
+usable in browsers, node, and workers.
+
+## Project documents
+
+`@needle-tools/addressing/document` exports the document types, evaluator,
+single-def/over application, optional inspection index, and schema validator.
+The JSON Schema is available at `@needle-tools/addressing/document/schema.json`.
+The document format is unchanged by this package split.
+
+The shared writer exports `writePropertyOver`, `captureDocumentValue`,
+`documentOverKey`, and `mergeDocumentOvers`. These encode property edits, retain
+addresses, remove net-undo edits, and merge saved overs. Hosts still supply node
+reference encoding, live-target checks, asset assembly, and component serialization.
+Non-finite numbers and unsupported values produce a writer issue instead of being
+silently changed by JSON serialization.
+
+`DocumentAssetAssembly` registers deduplicated asset sources and shared material
+or HDR entities in the writer's asset/reference tables. Material assignments reuse
+saved entity identities by source and material ID, even when asset keys change.
+Hosts supply the captured entity IDs and resolve asset ownership; the assembly
+contains no engine or editor dependencies.
+
+The evaluator accepts a `DocumentRuntime` host. It owns asset caching, reference
+placement, derived glTF IDs, target resolution, defs, property and parent overs,
+entity sharing, and issue reporting. The host supplies loading, object creation,
+cloning, and lifecycle scheduling. Needle Engine provides its own adapter;
+plain three.js can use the same evaluator:
+
+```ts
+import { Color, Object3D, Scene } from "three";
+import { GLTFLoader } from "three/examples/jsm/loaders/GLTFLoader.js";
+import { evaluateProjectDocument, type DocumentRuntime } from "@needle-tools/addressing/document";
+
+const scene = new Scene();
+const runtime: DocumentRuntime = {
+    scene,
+    renderer, // your existing renderer, for $renderer opinions
+    createNode: () => new Object3D(),
+    createColor: value => new Color().fromArray(value),
+    parse: (data, src) => new GLTFLoader().parseAsync(data, new URL(".", new URL(src, documentUrl)).href),
+    instantiate: node => (node as Object3D).clone(),
+    // Plain objects have no component lifecycle or template registrations.
+    parkTemplate() {},
+    activateInstance() {},
+    disposeTemplate() {},
+    schedule: work => work(),
+    loadEnvironment, // your existing HDR/PMREM loader: (url, options) => Promise<Texture | null>
+};
+const result = await evaluateProjectDocument(runtime, document, { baseUrl: documentUrl });
+await result.completed;
+```
+
+Supply `createDefContext` and the component access hooks if the host supports
+components. Without them, component defs are reported as unsupported; node defs
+and ordinary three.js properties still work. A skeletal or component-aware host
+must supply its matching clone implementation. The default addressing entry point
+does not import the document evaluator or any three.js runtime.
+
+## Ids
+
+Every glTF root-collection element (nodes, scenes, animations, cameras, materials,
+meshes, skins, textures, images, samplers) can carry a UUID in `extras["needle-id"]`:
+
+- **Anchored** — the element name ends with `#needle` (case-insensitive): the id derives
+  only from the text before the marker → it **survives any content change** as long as
+  the name stays. Spaces and underscores in the value are treated as equal (loaders
+  sanitize node names), so `Door Frame #needle` and `Door_Frame_#needle` share one id.
+- **Unanchored**: the id derives from the element's type, name, and its occurrence among
+  same-named elements → uniquely named elements keep their ids across reorders and
+  content updates; duplicates disambiguate by position within their name group; unnamed
+  elements are positional.
+
+`ensureIds(gltfJson)` stamps a parsed glTF idempotently — existing ids are never
+overwritten, and any tool stamping the same element mints the same id.
+
+`ensureIds(gltfJson, { baseHash })` optionally salts unanchored ids with a caller-supplied
+identity (e.g. a stable asset id), scoping them to that identity.
+
+## Addresses
+
+An address captures every fallback at creation time, while the target is known —
+`{ id, anchor?, type?, name?, path? }`. Resolution order is strict (path: "/"-separated segments, JSON-Pointer `~0`/`~1` escaping):
+
+1. `id` — exact match (`extras` in glTF JSON, `userData` in live scene graphs)
+2. `anchor` — survives asset updates
+3. `path` — best-effort structural match
+
+Node paths qualify same-named siblings with `~2n` (zero-based occurrence):
+`Cube~21` names the second `Cube`. Literal tildes remain escaped as `~0`.
+Unqualified ambiguous paths fail to resolve rather than picking the first child.
+These paths assume the original sibling order; use authored anchors or persistent
+IDs when the source scene changes.
+4. **reconciliation** — never automatic: `reconcileInGraph` returns ranked candidates
+   with confidence + reasons; the caller decides thresholds and whether to re-anchor.
+
+## API
+
+```ts
+import {
+    ensureIds, computeElementId, computeFileHash,         // write side
+    createGltfElementAddress, createObjectAddress,        // address records
+    resolveInGltf, resolveInGraph, reconcileInGraph,      // resolve side
+    parseAnchorValue, randomUuid, NEEDLE_ID_KEY,
+} from "@needle-tools/addressing";
+
+// stamp a parsed glTF (idempotent, never overwrites existing ids)
+const { fileHash, assigned } = ensureIds(gltfJson);
+
+// capture an address while the target is known
+const address = createObjectAddress(sceneRoot, targetObject);
+
+// later / elsewhere: resolve — or reconcile when the asset changed
+const hit = resolveInGraph(address, sceneRoot);
+const candidates = hit ? [] : reconcileInGraph(address, sceneRoot);
+```
+
+Out of scope by design: GLB container parsing (this package takes parsed JSON), file
+I/O, and any composition/override semantics.
+
+## Development
+
+```
+npm install
+npm test        # vitest — includes golden-fixture id tests
+npm run build   # tsc → dist/
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@needle-tools/addressing",
-  "version": "0.3.4-1790936280.dramatic-tiramisu.86ca165",
+  "version": "0.4.0",
   "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",
@@ -47,4 +47,4 @@
     "type": "git",
     "url": "https://github.com/needle-tools/addressing.git"
   }
-}
+}

package/src/address.ts

@@ -1,169 +1,169 @@
-import { parseAnchorValue } from "./anchor.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) → `path`
- * (best-effort) → reconciliation (candidates + confidence, never a silent guess).
- */
-export type NeedleAddress = {
-    /** the element's needle-id (deterministic for file-backed content, random for scratch) */
-    id?: string;
-    /** `#needle` anchor value, when the target's name carries one */
-    anchor?: string;
-    /** element type (`node`, `material`, …) — narrows resolution and validates matches */
-    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. 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".
-     * A `~2n` suffix selects the zero-based occurrence among same-named siblings.
-     */
-    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;
-    children?: readonly GraphNode[];
-    userData?: Record<string, unknown>;
-};
-
-/** 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;
-    const element = collection[index];
-    if (element == null || typeof element !== "object") return null;
-
-    const name = typeof element.name === "string" ? element.name : undefined;
-    const address: NeedleAddress = { type };
-    const id = getElementId(element);
-    if (id) address.id = id;
-    const anchor = parseAnchorValue(name);
-    if (anchor) address.anchor = anchor;
-    // an empty name is non-information: resolution never reads `name` (id → anchor →
-    // 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 segments = gltfNodeNamePath(json, index);
-        if (segments) address.path = segments.join("/");
-    }
-    return address;
-}
-
-/** Build an address for a live scene-graph object under `root`. */
-export function createObjectAddress(root: GraphNode, target: GraphNode): NeedleAddress | 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; path segments stay verbatim
-    if (target.name) address.name = target.name;
-    let parent = root;
-    address.path = nodes.map(node => {
-        const siblings = parent.children ?? [];
-        parent = node;
-        return nodePathSegment(node.name ?? "", siblings, node);
-    }).join("/");
-    return address;
-}
-
-/** `~2n` selects a same-named sibling; literal tildes were already escaped as `~0`. */
-function nodePathSegment(name: string, siblings: readonly GraphNode[], node: GraphNode): string {
-    const matches = siblings.filter(sibling => (sibling.name ?? "") === name);
-    const escaped = encodePathSegment(name);
-    return matches.length > 1 ? `${escaped}~2${matches.indexOf(node)}` : escaped;
-}
-
-export function splitNodePath(path: string): Array<{ name: string; occurrence?: number }> {
-    return path.split("/").map(segment => {
-        const qualifier = /~2(0|[1-9][0-9]*)$/.exec(segment);
-        return qualifier
-            ? { name: decodePathSegment(segment.slice(0, qualifier.index)), occurrence: Number(qualifier[1]) }
-            : { name: decodePathSegment(segment) };
-    });
-}
-
-export function collectionKeyForType(type: string): string {
-    // glTF collection keys are the pluralized type names; only "mesh" is irregular
-    return type === "mesh" ? "meshes" : `${type}s`;
-}
-
-/** names from root (exclusive) to the node at `nodeIndex` (inclusive), via the scene tree */
-function gltfNodeNamePath(json: GltfJson, nodeIndex: number): string[] | null {
-    const nodes = json["nodes"];
-    if (!Array.isArray(nodes)) return null;
-    const parents = new Map<number, number>();
-    for (let i = 0; i < nodes.length; i++) {
-        const children = nodes[i]?.children;
-        if (Array.isArray(children)) for (const c of children) parents.set(c, i);
-    }
-    const path: string[] = [];
-    let current: number | undefined = nodeIndex;
-    const seen = new Set<number>();
-    while (current !== undefined) {
-        if (seen.has(current)) return null; // malformed (cyclic) input
-        seen.add(current);
-        const parent = parents.get(current);
-        const siblingIndices: number[] = parent !== undefined ? nodes[parent]?.children ?? []
-            : [...new Set((Array.isArray(json.scenes) ? json.scenes : []).flatMap(scene => scene.nodes ?? []))];
-        path.unshift(nodePathSegment(typeof nodes[current]?.name === "string" ? nodes[current].name : "", siblingIndices.map(i => nodes[i]), nodes[current]));
-        current = parents.get(current);
-    }
-    return path;
-}
-
-/** path from root (exclusive) to target (inclusive), or null if target is not under root */
-export function findPath(root: GraphNode, target: GraphNode): GraphNode[] | null {
-    if (root === target) return [];
-    const children = root.children;
-    if (!children) return null;
-    for (let i = 0; i < children.length; i++) {
-        const child = children[i];
-        if (child == null) continue;
-        const sub = findPath(child, target);
-        if (sub) return [child, ...sub];
-    }
-    return null;
-}
+import { parseAnchorValue } from "./anchor.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) → `path`
+ * (best-effort) → reconciliation (candidates + confidence, never a silent guess).
+ */
+export type NeedleAddress = {
+    /** the element's needle-id (deterministic for file-backed content, random for scratch) */
+    id?: string;
+    /** `#needle` anchor value, when the target's name carries one */
+    anchor?: string;
+    /** element type (`node`, `material`, …) — narrows resolution and validates matches */
+    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. 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".
+     * A `~2n` suffix selects the zero-based occurrence among same-named siblings.
+     */
+    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;
+    children?: readonly GraphNode[];
+    userData?: Record<string, unknown>;
+};
+
+/** 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;
+    const element = collection[index];
+    if (element == null || typeof element !== "object") return null;
+
+    const name = typeof element.name === "string" ? element.name : undefined;
+    const address: NeedleAddress = { type };
+    const id = getElementId(element);
+    if (id) address.id = id;
+    const anchor = parseAnchorValue(name);
+    if (anchor) address.anchor = anchor;
+    // an empty name is non-information: resolution never reads `name` (id → anchor →
+    // 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 segments = gltfNodeNamePath(json, index);
+        if (segments) address.path = segments.join("/");
+    }
+    return address;
+}
+
+/** Build an address for a live scene-graph object under `root`. */
+export function createObjectAddress(root: GraphNode, target: GraphNode): NeedleAddress | 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; path segments stay verbatim
+    if (target.name) address.name = target.name;
+    let parent = root;
+    address.path = nodes.map(node => {
+        const siblings = parent.children ?? [];
+        parent = node;
+        return nodePathSegment(node.name ?? "", siblings, node);
+    }).join("/");
+    return address;
+}
+
+/** `~2n` selects a same-named sibling; literal tildes were already escaped as `~0`. */
+function nodePathSegment(name: string, siblings: readonly GraphNode[], node: GraphNode): string {
+    const matches = siblings.filter(sibling => (sibling.name ?? "") === name);
+    const escaped = encodePathSegment(name);
+    return matches.length > 1 ? `${escaped}~2${matches.indexOf(node)}` : escaped;
+}
+
+export function splitNodePath(path: string): Array<{ name: string; occurrence?: number }> {
+    return path.split("/").map(segment => {
+        const qualifier = /~2(0|[1-9][0-9]*)$/.exec(segment);
+        return qualifier
+            ? { name: decodePathSegment(segment.slice(0, qualifier.index)), occurrence: Number(qualifier[1]) }
+            : { name: decodePathSegment(segment) };
+    });
+}
+
+export function collectionKeyForType(type: string): string {
+    // glTF collection keys are the pluralized type names; only "mesh" is irregular
+    return type === "mesh" ? "meshes" : `${type}s`;
+}
+
+/** names from root (exclusive) to the node at `nodeIndex` (inclusive), via the scene tree */
+function gltfNodeNamePath(json: GltfJson, nodeIndex: number): string[] | null {
+    const nodes = json["nodes"];
+    if (!Array.isArray(nodes)) return null;
+    const parents = new Map<number, number>();
+    for (let i = 0; i < nodes.length; i++) {
+        const children = nodes[i]?.children;
+        if (Array.isArray(children)) for (const c of children) parents.set(c, i);
+    }
+    const path: string[] = [];
+    let current: number | undefined = nodeIndex;
+    const seen = new Set<number>();
+    while (current !== undefined) {
+        if (seen.has(current)) return null; // malformed (cyclic) input
+        seen.add(current);
+        const parent = parents.get(current);
+        const siblingIndices: number[] = parent !== undefined ? nodes[parent]?.children ?? []
+            : [...new Set((Array.isArray(json.scenes) ? json.scenes : []).flatMap(scene => scene.nodes ?? []))];
+        path.unshift(nodePathSegment(typeof nodes[current]?.name === "string" ? nodes[current].name : "", siblingIndices.map(i => nodes[i]), nodes[current]));
+        current = parents.get(current);
+    }
+    return path;
+}
+
+/** path from root (exclusive) to target (inclusive), or null if target is not under root */
+export function findPath(root: GraphNode, target: GraphNode): GraphNode[] | null {
+    if (root === target) return [];
+    const children = root.children;
+    if (!children) return null;
+    for (let i = 0; i < children.length; i++) {
+        const child = children[i];
+        if (child == null) continue;
+        const sub = findPath(child, target);
+        if (sub) return [child, ...sub];
+    }
+    return null;
+}