@needle-tools/addressing 0.1.0 → 0.3.0

package/Readme.md

@@ -1,89 +1,69 @@
-# @needle-tools/addressing
-
-Persistent addressing for Needle assets: deterministic `needle-id` computation, the
-`#needle` anchor scheme, and address resolution over glTF JSON and live scene graphs.
-
-Zero runtime dependencies, no three.js or engine import (duck-typed scene graphs), usable
-in browsers, node, and workers. This package is the **single implementation of the
-addressing contract** shared by needle-cloud (upload-time id injection), the Needle
-editors (load-time computation, address records for edits/marks/overlays), and Needle
-Engine (project-document resolution at load).
-
-## The contract
-
-### Deterministic ids (`needle-id`)
-
-Every glTF root-collection element (nodes, scenes, animations, cameras, materials,
-meshes, skins, textures, images, samplers) gets a UUID in `extras["needle-id"]`:
-
-- **Anchored** — name ends with `#needle` (case-insensitive):
-  `uuidv5("<type>-<anchor>", URL_NAMESPACE)`. Independent of index and file content →
-  **survives asset updates** as long as the name stays.
-- **Unanchored**: `uuidv5("<type>-<name>-<index>-<fileHash>", URL_NAMESPACE)` where
-  `fileHash = md5hex(JSON.stringify(json))` of the file **before any injection**.
-  Stable per asset *version* only — re-uploading changed content changes these ids
-  (by design: same-named elements in different files must not collide).
-
-Compatibility is pinned by golden tests against the original implementation
-(needle-cloud `gltf.edit.ts` `ensureUUID`, real `js-md5` + `uuid` packages). This
-includes a frozen quirk: the anchor value's cut index is computed from the trimmed name
-but applied to the raw name, so leading whitespace shifts the anchor
-(`"  Trim#NEEDLE"` → anchor `"Tr"`). Do not "fix" this — it would change every anchored
-id minted for such names.
-
-### Who writes ids when
-
-- **needle-cloud**: injects on upload (frontend today; CLI/optimizer parity planned).
-- **Editors**: **eager compute, lazy persist.** Compute ids at LOAD time against the
-  pristine JSON (the inputs — original name, index, file hash — only exist pristinely
-  then; computing after edits breaks determinism). Persist into the file only on save.
-  A locally saved file is stamped identically to a cloud upload of the same bytes.
-- **Scratch content** (created in an editor, no source file): `randomUuid()` at creation.
-
-### Address records
-
-An address is "fat": every fallback is captured at creation time, while the target is
-known — `{ id, anchor?, type?, name?, namePath? }`. Resolution order is strict:
-
-1. `id` — exact match (extras in glTF, `userData` in live graphs)
-2. `anchor` — survives asset updates
-3. `namePath` — best-effort structural match
-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 (callers own their binary handling — this
-package takes parsed JSON), file I/O, session-scoped editor refs, and any composition/
-override semantics (those live in the project format, one layer above).
-
-## Development
-
-```
-npm install
-npm test        # vitest — includes byte-parity golden tests
-npm run build   # tsc → dist/
-```
-
-Regenerating `test/fixtures/golden.json` requires the reference libraries
-(`js-md5`, `uuid`) and a verbatim copy of needle-cloud's `ensureUUID` — see the
-fixture header comment in `test/id.test.ts`.
+# @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.
+
+## 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.
+- **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?, namePath? }`. Resolution order is strict:
+
+1. `id` — exact match (`extras` in glTF JSON, `userData` in live scene graphs)
+2. `anchor` — survives asset updates
+3. `namePath` — best-effort structural match
+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,35 +1,39 @@
-{
-    "name": "@needle-tools/addressing",
-    "version": "0.1.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",
-    "types": "./src/index.ts",
-    "exports": {
-        ".": {
-            "types": "./src/index.ts",
-            "default": "./src/index.ts"
-        }
-    },
-    "files": [
-        "src",
-        "Readme.md"
-    ],
-    "scripts": {
-        "build": "tsc -p tsconfig.json",
-        "test": "vitest run"
-    },
-    "author": {
-        "name": "Needle",
-        "email": "hi@needle.tools",
-        "url": "https://needle.tools"
-    },
-    "devDependencies": {
-        "typescript": "^5.6.0",
-        "vitest": "^3.0.0"
-    },
-    "publishConfig": {
-        "access": "public",
-        "registry": "https://registry.npmjs.org"
-    }
-}
+{
+  "name": "@needle-tools/addressing",
+  "version": "0.3.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",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "files": [
+    "src",
+    "Readme.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run"
+  },
+  "author": {
+    "name": "Needle",
+    "email": "hi@needle.tools",
+    "url": "https://needle.tools"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0",
+    "vitest": "^3.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/needle-tools/addressing.git"
+  }
+}

package/src/address.ts

@@ -1,106 +1,106 @@
-import { parseAnchorValue } from "./anchor.js";
-import { getElementId, GltfJson, NEEDLE_ID_KEY, 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`
- * (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 */
-    namePath?: string[];
-};
-
-/** 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. `namePath` 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;
-    if (name !== undefined) address.name = name;
-    if (type === "node") {
-        const path = gltfNodeNamePath(json, index);
-        if (path) address.namePath = path;
-    }
-    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 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;
-    if (typeof target.name === "string") address.name = target.name;
-    address.namePath = path.map(n => n.name ?? "");
-    return address;
-}
-
-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);
-        path.unshift(typeof nodes[current]?.name === "string" ? nodes[current].name : "");
-        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, GltfJson, NEEDLE_ID_KEY, 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`
+ * (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 */
+    namePath?: string[];
+};
+
+/** 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. `namePath` 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;
+    if (name !== undefined) address.name = name;
+    if (type === "node") {
+        const path = gltfNodeNamePath(json, index);
+        if (path) address.namePath = path;
+    }
+    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 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;
+    if (typeof target.name === "string") address.name = target.name;
+    address.namePath = path.map(n => n.name ?? "");
+    return address;
+}
+
+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);
+        path.unshift(typeof nodes[current]?.name === "string" ? nodes[current].name : "");
+        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;
+}

package/src/anchor.ts

@@ -37,9 +37,7 @@ export function parseAnchor(rawName: string | null | undefined): ParsedAnchor |
     const lower = trimmed.toLowerCase();
     for (const marker of byLengthDescending(ANCHOR_MARKERS)) {
         if (!lower.endsWith(marker)) continue;
-        const value = marker === ANCHOR_MARKER
-            ? legacyNeedleAnchorValue(rawName, trimmed)
-            : trimmed.substring(0, trimmed.length - marker.length).trim();
+        const value = trimmed.substring(0, trimmed.length - marker.length).trim();
         return value.length > 0 ? { marker, value } : null;
     }
     return null;
@@ -53,19 +51,6 @@ export function parseAnchorValue(rawName: string | null | undefined): string | n
     return parseAnchor(rawName)?.value ?? null;
 }
 
-/**
- * `#needle` value extraction, bug-compatible with needle-cloud's `ensureUUID`
- * (`gltf.edit.ts`), which computes the cut index from the TRIMMED name but applies it to
- * the RAW name: a name with leading whitespace yields a shifted (shorter) anchor value
- * (`"  Trim#NEEDLE"` → `"Tr"`). Anchored ids are the ids that must survive asset
- * updates, so this quirk is frozen into the contract for THIS marker — fixing it would
- * change every anchored id ever minted for such names. Future markers use the clean
- * trimmed parsing in {@link parseAnchor} instead.
- */
-function legacyNeedleAnchorValue(rawName: string, trimmed: string): string {
-    return rawName.substring(0, trimmed.length - ANCHOR_MARKER.length).trim();
-}
-
 function byLengthDescending(markers: readonly string[]): readonly string[] {
     return markers.length > 1 ? [...markers].sort((a, b) => b.length - a.length) : markers;
 }

package/src/gltf.ts

@@ -1,71 +1,89 @@
-import { computeElementId, computeFileHash } from "./id.js";
-
-/** The glTF `extras` key carrying the persistent id. */
-export const NEEDLE_ID_KEY = "needle-id";
-
-/** All root-collection element types that receive ids, with their glTF collection key. */
-export const STAMPED_COLLECTIONS = [
-    ["node", "nodes"],
-    ["scene", "scenes"],
-    ["animation", "animations"],
-    ["camera", "cameras"],
-    ["material", "materials"],
-    ["mesh", "meshes"],
-    ["skin", "skins"],
-    ["texture", "textures"],
-    ["image", "images"],
-    ["sampler", "samplers"],
-] as const satisfies ReadonlyArray<readonly [string, string]>;
-
-export type StampedElementType = (typeof STAMPED_COLLECTIONS)[number][0];
-
-/** Structural (duck-typed) view of a glTF root element — no glTF library dependency. */
-export type GltfElement = {
-    name?: string;
-    extras?: Record<string, unknown>;
-    [key: string]: unknown;
-};
-
-/** Structural view of a glTF JSON root. Collections are looked up by key. */
-export type GltfJson = {
-    [collection: string]: unknown;
-};
-
-export type EnsureIdsResult = {
-    /** the file fingerprint the ids were derived from (of the json BEFORE injection) */
-    fileHash: 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 cloud-stamped files pass through
- * unchanged and editor-computed ids agree with what the cloud minted for the same bytes.
- *
- * Mutates `json` in place (same shape as needle-cloud's upload-time `ensureUUID`).
- */
-export function ensureIds(json: GltfJson): EnsureIdsResult {
-    const fileHash = computeFileHash(json);
-    let assigned = 0;
-    for (const [type, collection] of STAMPED_COLLECTIONS) {
-        const elements = json[collection];
-        if (!Array.isArray(elements)) continue;
-        for (let index = 0; index < elements.length; index++) {
-            const element = elements[index] as GltfElement;
-            if (element == null || typeof element !== "object") continue;
-            element.extras ??= {};
-            if (element.extras[NEEDLE_ID_KEY] === undefined) {
-                element.extras[NEEDLE_ID_KEY] = computeElementId(type, element.name, index, fileHash);
-                assigned++;
-            }
-        }
-    }
-    return { fileHash, 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;
-}
+import { computeElementId } from "./id.js";
+
+/** The glTF `extras` key carrying the persistent id. */
+export const NEEDLE_ID_KEY = "needle-id";
+
+/** All root-collection element types that receive ids, with their glTF collection key. */
+export const STAMPED_COLLECTIONS = [
+    ["node", "nodes"],
+    ["scene", "scenes"],
+    ["animation", "animations"],
+    ["camera", "cameras"],
+    ["material", "materials"],
+    ["mesh", "meshes"],
+    ["skin", "skins"],
+    ["texture", "textures"],
+    ["image", "images"],
+    ["sampler", "samplers"],
+] as const satisfies ReadonlyArray<readonly [string, string]>;
+
+export type StampedElementType = (typeof STAMPED_COLLECTIONS)[number][0];
+
+/** Structural (duck-typed) view of a glTF root element — no glTF library dependency. */
+export type GltfElement = {
+    name?: string;
+    extras?: Record<string, unknown>;
+    [key: string]: unknown;
+};
+
+/** Structural view of a glTF JSON root. Collections are looked up by key. */
+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
+        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 occurrence = occurrences.get(name) ?? 0;
+            occurrences.set(name, 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;
+}