@needle-tools/addressing 0.3.1-1784560466.reasonable-waffle.0dfaf15 → 0.3.2

package/Readme.md

@@ -1,69 +1,70 @@
-# @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/
-```
+# @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. 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?, 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/dist/address.d.ts

@@ -0,0 +1,34 @@
+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`
+ * (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 declare function createGltfElementAddress(json: GltfJson, type: StampedElementType | string, index: number): NeedleAddress | null;
+/** Build an address for a live scene-graph object under `root`. */
+export declare function createObjectAddress(root: GraphNode, target: GraphNode): NeedleAddress | null;
+export declare function collectionKeyForType(type: string): string;
+/** path from root (exclusive) to target (inclusive), or null if target is not under root */
+export declare function findPath(root: GraphNode, target: GraphNode): GraphNode[] | null;

package/dist/address.js

@@ -0,0 +1,89 @@
+import { parseAnchorValue } from "./anchor.js";
+import { getElementId, NEEDLE_ID_KEY } from "./gltf.js";
+/** Build an address for a glTF root-collection element. `namePath` only applies to nodes. */
+export function createGltfElementAddress(json, type, index) {
+    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 = { 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, target) {
+    const path = findPath(root, target);
+    if (!path)
+        return null;
+    const address = { 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) {
+    // 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, nodeIndex) {
+    const nodes = json["nodes"];
+    if (!Array.isArray(nodes))
+        return null;
+    const parents = new Map();
+    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 = [];
+    let current = nodeIndex;
+    const seen = new Set();
+    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, target) {
+    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/dist/anchor.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The name-anchor scheme: an element named `Door #needle` derives its deterministic id
+ * from the text before the marker instead of (name, index, file hash) — so the id
+ * survives content changes and asset re-uploads as long as the name stays.
+ *
+ * CONTRACT NOTE — the marker set is part of the id contract. Markers may be ADDED (new
+ * names start anchoring), but never removed or re-prioritized, and every WRITER of ids
+ * (this package's consumers: cloud upload, editors, CLI) must agree on the set before a
+ * new marker ships — a writer that anchors on a marker another writer doesn't know mints
+ * DIFFERENT ids for the same file. The anchored id only hashes the VALUE (not the
+ * marker), so all markers are aliases into the same id space.
+ */
+/** the original marker — kept as a named export for existing consumers */
+export declare const ANCHOR_MARKER = "#needle";
+/**
+ * All recognized markers, matched longest-first so overlapping suffixes resolve
+ * deterministically. Currently one entry; see the contract note before adding more.
+ */
+export declare const ANCHOR_MARKERS: readonly string[];
+export type ParsedAnchor = {
+    /** the marker that matched (one of {@link ANCHOR_MARKERS}) */
+    marker: string;
+    /** the anchor value — the deterministic-id input */
+    value: string;
+};
+/**
+ * Parse an element name against all recognized markers (case-insensitive suffix match).
+ * Returns null when no marker matches or the anchor value is empty.
+ */
+export declare function parseAnchor(rawName: string | null | undefined): ParsedAnchor | null;
+/**
+ * Extract the anchor value from an element name, or null when the name carries no anchor.
+ * Convenience over {@link parseAnchor} for callers that only need the id input.
+ */
+export declare function parseAnchorValue(rawName: string | null | undefined): string | null;

package/dist/anchor.js

@@ -0,0 +1,57 @@
+/**
+ * The name-anchor scheme: an element named `Door #needle` derives its deterministic id
+ * from the text before the marker instead of (name, index, file hash) — so the id
+ * survives content changes and asset re-uploads as long as the name stays.
+ *
+ * CONTRACT NOTE — the marker set is part of the id contract. Markers may be ADDED (new
+ * names start anchoring), but never removed or re-prioritized, and every WRITER of ids
+ * (this package's consumers: cloud upload, editors, CLI) must agree on the set before a
+ * new marker ships — a writer that anchors on a marker another writer doesn't know mints
+ * DIFFERENT ids for the same file. The anchored id only hashes the VALUE (not the
+ * marker), so all markers are aliases into the same id space.
+ */
+/** the original marker — kept as a named export for existing consumers */
+export const ANCHOR_MARKER = "#needle";
+/**
+ * All recognized markers, matched longest-first so overlapping suffixes resolve
+ * deterministically. Currently one entry; see the contract note before adding more.
+ */
+export const ANCHOR_MARKERS = [ANCHOR_MARKER];
+/**
+ * Parse an element name against all recognized markers (case-insensitive suffix match).
+ * Returns null when no marker matches or the anchor value is empty.
+ */
+export function parseAnchor(rawName) {
+    if (rawName == null)
+        return null;
+    const trimmed = rawName.trim();
+    const lower = trimmed.toLowerCase();
+    for (const marker of byLengthDescending(ANCHOR_MARKERS)) {
+        if (!lower.endsWith(marker))
+            continue;
+        const value = normalizeAnchorValue(trimmed.substring(0, trimmed.length - marker.length));
+        return value.length > 0 ? { marker, value } : null;
+    }
+    return null;
+}
+/**
+ * Anchor values treat SPACES and UNDERSCORES as the same character (runs collapse to
+ * one space): three's GLTFLoader sanitizes node names on load (whitespace becomes
+ * "_"), so "Door Frame #needle" appears live as "Door_Frame_#needle" — without
+ * normalization the stamped anchor and the live anchor would never match. Applied at
+ * PARSE time, so id computation and resolution agree from one change point. Accepted
+ * trade: names differing only by space-vs-underscore share one anchor.
+ */
+function normalizeAnchorValue(value) {
+    return value.replace(/[\s_]+/g, " ").trim();
+}
+/**
+ * Extract the anchor value from an element name, or null when the name carries no anchor.
+ * Convenience over {@link parseAnchor} for callers that only need the id input.
+ */
+export function parseAnchorValue(rawName) {
+    return parseAnchor(rawName)?.value ?? null;
+}
+function byLengthDescending(markers) {
+    return markers.length > 1 ? [...markers].sort((a, b) => b.length - a.length) : markers;
+}

package/dist/gltf.d.ts

@@ -0,0 +1,41 @@
+/** The glTF `extras` key carrying the persistent id. */
+export declare const NEEDLE_ID_KEY = "needle-id";
+/** All root-collection element types that receive ids, with their glTF collection key. */
+export declare const STAMPED_COLLECTIONS: readonly [readonly ["node", "nodes"], readonly ["scene", "scenes"], readonly ["animation", "animations"], readonly ["camera", "cameras"], readonly ["material", "materials"], readonly ["mesh", "meshes"], readonly ["skin", "skins"], readonly ["texture", "textures"], readonly ["image", "images"], readonly ["sampler", "samplers"]];
+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 declare function ensureIds(json: GltfJson, options?: EnsureIdsOptions): EnsureIdsResult;
+/** Read an element's needle-id without computing anything. */
+export declare function getElementId(element: GltfElement | null | undefined): string | null;

package/dist/gltf.js

@@ -0,0 +1,55 @@
+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"],
+];
+/**
+ * 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, options) {
+    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();
+        for (let index = 0; index < elements.length; index++) {
+            const element = elements[index];
+            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 ?? (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) {
+    const id = element?.extras?.[NEEDLE_ID_KEY];
+    return typeof id === "string" ? id : null;
+}

package/dist/hash.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Vendored SHA-1 so the package has zero runtime dependencies — it backs UUIDv5
+ * (RFC 4122). Correctness is pinned by golden tests against the `uuid` npm package.
+ */
+/** SHA-1 digest bytes of `data`. */
+export declare function sha1(data: Uint8Array): Uint8Array;
+export declare function toHex(bytes: Uint8Array): string;

package/dist/hash.js

@@ -0,0 +1,75 @@
+/**
+ * Vendored SHA-1 so the package has zero runtime dependencies — it backs UUIDv5
+ * (RFC 4122). Correctness is pinned by golden tests against the `uuid` npm package.
+ */
+/** SHA-1 digest bytes of `data`. */
+export function sha1(data) {
+    const padded = padMessage(data);
+    const dv = new DataView(padded.buffer, padded.byteOffset, padded.byteLength);
+    let h0 = 0x67452301, h1 = 0xefcdab89, h2 = 0x98badcfe, h3 = 0x10325476, h4 = 0xc3d2e1f0;
+    const w = new Uint32Array(80);
+    for (let off = 0; off < padded.length; off += 64) {
+        for (let i = 0; i < 16; i++)
+            w[i] = dv.getUint32(off + i * 4);
+        for (let i = 16; i < 80; i++) {
+            const n = w[i - 3] ^ w[i - 8] ^ w[i - 14] ^ w[i - 16];
+            w[i] = (n << 1) | (n >>> 31);
+        }
+        let a = h0, b = h1, c = h2, d = h3, e = h4;
+        for (let i = 0; i < 80; i++) {
+            let f, k;
+            if (i < 20) {
+                f = (b & c) | (~b & d);
+                k = 0x5a827999;
+            }
+            else if (i < 40) {
+                f = b ^ c ^ d;
+                k = 0x6ed9eba1;
+            }
+            else if (i < 60) {
+                f = (b & c) | (b & d) | (c & d);
+                k = 0x8f1bbcdc;
+            }
+            else {
+                f = b ^ c ^ d;
+                k = 0xca62c1d6;
+            }
+            const t = ((((a << 5) | (a >>> 27)) + f + e + k + w[i]) | 0);
+            e = d;
+            d = c;
+            c = (b << 30) | (b >>> 2);
+            b = a;
+            a = t;
+        }
+        h0 = (h0 + a) | 0;
+        h1 = (h1 + b) | 0;
+        h2 = (h2 + c) | 0;
+        h3 = (h3 + d) | 0;
+        h4 = (h4 + e) | 0;
+    }
+    const out = new Uint8Array(20);
+    const odv = new DataView(out.buffer);
+    odv.setUint32(0, h0 >>> 0);
+    odv.setUint32(4, h1 >>> 0);
+    odv.setUint32(8, h2 >>> 0);
+    odv.setUint32(12, h3 >>> 0);
+    odv.setUint32(16, h4 >>> 0);
+    return out;
+}
+export function toHex(bytes) {
+    let s = "";
+    for (let i = 0; i < bytes.length; i++)
+        s += bytes[i].toString(16).padStart(2, "0");
+    return s;
+}
+/** append 0x80, zero-pad to 56 mod 64, append big-endian 64-bit bit-length */
+function padMessage(data) {
+    const bitLen = data.length * 8;
+    const padded = new Uint8Array((((data.length + 8) >> 6) + 1) * 64);
+    padded.set(data);
+    padded[data.length] = 0x80;
+    const dv = new DataView(padded.buffer);
+    dv.setUint32(padded.length - 8, Math.floor(bitLen / 0x100000000));
+    dv.setUint32(padded.length - 4, bitLen >>> 0);
+    return padded;
+}

package/dist/id.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The deterministic needle-id of a glTF element.
+ *
+ * - Anchored name (`… #needle`): `uuidv5("<type>-<anchor>")` — survives ANY content
+ *   change while the name stays.
+ * - Otherwise: `uuidv5("<type>-<name>-<occurrence>[-<baseHash>]")` where `occurrence`
+ *   is the element's position among SAME-NAMED elements of its type. Uniquely named
+ *   elements are therefore fully reorder-stable across file versions; duplicates shift
+ *   only when reordered within their own name group; unnamed elements are positional
+ *   among the unnamed.
+ * - `baseHash` is an optional consumer-supplied salt (e.g. an asset/content id) that
+ *   scopes ids to an external identity. Omitted by default, so any tool stamping the
+ *   same element mints the same id with no coordination.
+ *
+ * Ids are persisted in `extras["needle-id"]` and never overwritten once present —
+ * whoever stamps first wins; this rule only governs never-stamped elements.
+ */
+export declare function computeElementId(type: string, name: string | null | undefined, occurrence: number, baseHash?: string): string;
+/**
+ * The occurrence of the element at `index` among same-named elements of its collection —
+ * the positional input of {@link computeElementId}. Exposed so consumers computing ids
+ * for individual elements (instead of stamping whole files) use the identical rule.
+ */
+export declare function occurrenceOfName(elements: ReadonlyArray<{
+    name?: unknown;
+} | null | undefined>, index: number): number;

package/dist/id.js

@@ -0,0 +1,43 @@
+import { parseAnchorValue } from "./anchor.js";
+import { uuidv5 } from "./uuid.js";
+/**
+ * The deterministic needle-id of a glTF element.
+ *
+ * - Anchored name (`… #needle`): `uuidv5("<type>-<anchor>")` — survives ANY content
+ *   change while the name stays.
+ * - Otherwise: `uuidv5("<type>-<name>-<occurrence>[-<baseHash>]")` where `occurrence`
+ *   is the element's position among SAME-NAMED elements of its type. Uniquely named
+ *   elements are therefore fully reorder-stable across file versions; duplicates shift
+ *   only when reordered within their own name group; unnamed elements are positional
+ *   among the unnamed.
+ * - `baseHash` is an optional consumer-supplied salt (e.g. an asset/content id) that
+ *   scopes ids to an external identity. Omitted by default, so any tool stamping the
+ *   same element mints the same id with no coordination.
+ *
+ * Ids are persisted in `extras["needle-id"]` and never overwritten once present —
+ * whoever stamps first wins; this rule only governs never-stamped elements.
+ */
+export function computeElementId(type, name, occurrence, baseHash) {
+    const anchor = parseAnchorValue(name);
+    const str = anchor !== null
+        ? `${type}-${anchor}`
+        : `${type}-${name ? name : ""}-${occurrence}${baseHash ? `-${baseHash}` : ""}`;
+    return uuidv5(str);
+}
+/**
+ * The occurrence of the element at `index` among same-named elements of its collection —
+ * the positional input of {@link computeElementId}. Exposed so consumers computing ids
+ * for individual elements (instead of stamping whole files) use the identical rule.
+ */
+export function occurrenceOfName(elements, index) {
+    const name = normalizedName(elements[index]);
+    let occurrence = 0;
+    for (let i = 0; i < index; i++) {
+        if (normalizedName(elements[i]) === name)
+            occurrence++;
+    }
+    return occurrence;
+}
+function normalizedName(element) {
+    return typeof element?.name === "string" ? element.name : "";
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { ANCHOR_MARKER, ANCHOR_MARKERS, parseAnchor, parseAnchorValue, type ParsedAnchor } from "./anchor.js";
+export { computeElementId, occurrenceOfName } from "./id.js";
+export { ensureIds, getElementId, NEEDLE_ID_KEY, STAMPED_COLLECTIONS, type EnsureIdsOptions, type EnsureIdsResult, type GltfElement, type GltfJson, type StampedElementType, } from "./gltf.js";
+export { collectionKeyForType, createGltfElementAddress, createObjectAddress, findPath, type GraphNode, type NeedleAddress, } from "./address.js";
+export { reconcileInGraph, resolveInGltf, resolveInGraph, type GltfResolveResult, type ReconcileCandidate, } from "./resolve.js";
+export { randomUuid, uuidv5, UUID_NAMESPACE_URL } from "./uuid.js";

package/dist/index.js

@@ -0,0 +1,6 @@
+export { ANCHOR_MARKER, ANCHOR_MARKERS, parseAnchor, parseAnchorValue } from "./anchor.js";
+export { computeElementId, occurrenceOfName } from "./id.js";
+export { ensureIds, getElementId, NEEDLE_ID_KEY, STAMPED_COLLECTIONS, } from "./gltf.js";
+export { collectionKeyForType, createGltfElementAddress, createObjectAddress, findPath, } from "./address.js";
+export { reconcileInGraph, resolveInGltf, resolveInGraph, } from "./resolve.js";
+export { randomUuid, uuidv5, UUID_NAMESPACE_URL } from "./uuid.js";