@needle-tools/addressing 0.1.1 → 0.3.0

package/Readme.md

@@ -12,15 +12,18 @@ Every glTF root-collection element (nodes, scenes, animations, cameras, material
 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 content changes and re-exports**
-  as long as the name stays.
-- **Unanchored**: the id derives from the element's type, name, index and a fingerprint
-  of the whole file → stable per asset *version* (same-named elements in different files
-  never collide).
+  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 stamping the same bytes always mints the same ids, no matter which tool
-does it.
+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
 

package/package.json

@@ -1,35 +1,39 @@
-{
-    "name": "@needle-tools/addressing",
-    "version": "0.1.1",
-    "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/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;
+}

package/src/hash.ts

@@ -1,113 +1,58 @@
-/**
- * Vendored hash primitives so the package has zero runtime dependencies.
- * md5Hex must produce byte-identical output to `js-md5`'s `md5(str)` (needle-cloud's
- * `hashStringMD5`) — the file fingerprint is part of the deterministic id contract.
- * sha1 backs UUIDv5 (RFC 4122).
- */
-
-const MD5_K = new Uint32Array(64);
-for (let i = 0; i < 64; i++) {
-    MD5_K[i] = Math.floor(Math.abs(Math.sin(i + 1)) * 0x100000000);
-}
-// per-round left-rotate amounts
-const MD5_S = [
-    7, 12, 17, 22, 7, 12, 17, 22, 7, 12, 17, 22, 7, 12, 17, 22,
-    5, 9, 14, 20, 5, 9, 14, 20, 5, 9, 14, 20, 5, 9, 14, 20,
-    4, 11, 16, 23, 4, 11, 16, 23, 4, 11, 16, 23, 4, 11, 16, 23,
-    6, 10, 15, 21, 6, 10, 15, 21, 6, 10, 15, 21, 6, 10, 15, 21,
-];
-
-/** MD5 of the UTF-8 encoding of `input`, as a lowercase hex string. */
-export function md5Hex(input: string | Uint8Array): string {
-    const data = typeof input === "string" ? new TextEncoder().encode(input) : input;
-    const padded = padMessage(data, /* littleEndianLength */ true);
-    const dv = new DataView(padded.buffer, padded.byteOffset, padded.byteLength);
-
-    let a0 = 0x67452301, b0 = 0xefcdab89, c0 = 0x98badcfe, d0 = 0x10325476;
-    const m = new Uint32Array(16);
-    for (let off = 0; off < padded.length; off += 64) {
-        for (let i = 0; i < 16; i++) m[i] = dv.getUint32(off + i * 4, true);
-        let a = a0, b = b0, c = c0, d = d0;
-        for (let i = 0; i < 64; i++) {
-            let f: number, g: number;
-            if (i < 16) { f = (b & c) | (~b & d); g = i; }
-            else if (i < 32) { f = (d & b) | (~d & c); g = (5 * i + 1) % 16; }
-            else if (i < 48) { f = b ^ c ^ d; g = (3 * i + 5) % 16; }
-            else { f = c ^ (b | ~d); g = (7 * i) % 16; }
-            const t = (f + a + MD5_K[i] + m[g]) | 0;
-            a = d; d = c; c = b;
-            b = (b + ((t << MD5_S[i]) | (t >>> (32 - MD5_S[i])))) | 0;
-        }
-        a0 = (a0 + a) | 0; b0 = (b0 + b) | 0; c0 = (c0 + c) | 0; d0 = (d0 + d) | 0;
-    }
-
-    const out = new Uint8Array(16);
-    const odv = new DataView(out.buffer);
-    odv.setUint32(0, a0 >>> 0, true);
-    odv.setUint32(4, b0 >>> 0, true);
-    odv.setUint32(8, c0 >>> 0, true);
-    odv.setUint32(12, d0 >>> 0, true);
-    return toHex(out);
-}
-
-/** SHA-1 digest bytes of `data`. */
-export function sha1(data: Uint8Array): Uint8Array {
-    const padded = padMessage(data, /* littleEndianLength */ false);
-    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: number, k: number;
-            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: Uint8Array): string {
-    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 64-bit bit-length (LE for MD5, BE for SHA-1) */
-function padMessage(data: Uint8Array, littleEndianLength: boolean): Uint8Array {
-    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);
-    const lo = bitLen >>> 0;
-    const hi = Math.floor(bitLen / 0x100000000);
-    if (littleEndianLength) {
-        dv.setUint32(padded.length - 8, lo, true);
-        dv.setUint32(padded.length - 4, hi, true);
-    }
-    else {
-        dv.setUint32(padded.length - 8, hi);
-        dv.setUint32(padded.length - 4, lo);
-    }
-    return padded;
-}
+/**
+ * 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: Uint8Array): Uint8Array {
+    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: number, k: number;
+            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: Uint8Array): string {
+    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: Uint8Array): Uint8Array {
+    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/src/id.ts

@@ -1,32 +1,45 @@
-import { parseAnchorValue } from "./anchor.js";
-import { md5Hex } from "./hash.js";
-import { uuidv5 } from "./uuid.js";
-
-/**
- * Fingerprint of a glTF file for deterministic id computation: MD5 hex of
- * `JSON.stringify(json)`, taken over the file AS-IS **before any ids are injected**
- * (needle-cloud hashes first, then mutates — order is part of the contract).
- */
-export function computeFileHash(json: unknown): string {
-    return md5Hex(JSON.stringify(json));
-}
-
-/**
- * The deterministic needle-id of a glTF element. Byte-identical to needle-cloud's
- * `ensureUUID` (upload-time injection):
- *
- * - anchored name (`… #needle`): `uuidv5("<type>-<anchor>", URL)` — stable across
- *   asset versions.
- * - otherwise: `uuidv5("<type>-<name>-<index>-<fileHash>", URL)` — stable per asset
- *   VERSION only (the file hash is an input by design: same-named elements in
- *   different files must not collide).
- *
- * `name` handling matches the source: absent/empty names contribute `""`.
- */
-export function computeElementId(type: string, name: string | null | undefined, index: number, fileHash: string): string {
-    const anchor = parseAnchorValue(name);
-    const str = anchor !== null
-        ? `${type}-${anchor}`
-        : `${type}-${name ? name : ""}-${index}-${fileHash}`;
-    return uuidv5(str);
-}
+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: string, name: string | null | undefined, occurrence: number, baseHash?: string): string {
+    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: ReadonlyArray<{ name?: unknown } | null | undefined>, index: number): number {
+    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: { name?: unknown } | null | undefined): string {
+    return typeof element?.name === "string" ? element.name : "";
+}

package/src/index.ts

@@ -1,10 +1,11 @@
 export { ANCHOR_MARKER, ANCHOR_MARKERS, parseAnchor, parseAnchorValue, type ParsedAnchor } from "./anchor.js";
-export { computeElementId, computeFileHash } from "./id.js";
+export { computeElementId, occurrenceOfName } from "./id.js";
 export {
     ensureIds,
     getElementId,
     NEEDLE_ID_KEY,
     STAMPED_COLLECTIONS,
+    type EnsureIdsOptions,
     type EnsureIdsResult,
     type GltfElement,
     type GltfJson,
@@ -26,4 +27,3 @@ export {
     type ReconcileCandidate,
 } from "./resolve.js";
 export { randomUuid, uuidv5, UUID_NAMESPACE_URL } from "./uuid.js";
-export { md5Hex } from "./hash.js";

package/src/resolve.ts

@@ -1,172 +1,172 @@
-import { parseAnchorValue } from "./anchor.js";
-import { collectionKeyForType, GraphNode, NeedleAddress } from "./address.js";
-import { GltfJson, NEEDLE_ID_KEY, STAMPED_COLLECTIONS } from "./gltf.js";
-
-export type GltfResolveResult = {
-    type: string;
-    index: number;
-    element: Record<string, unknown>;
-};
-
-/**
- * Resolve an address inside glTF JSON. Tries id → anchor → namePath (nodes), in that
- * order; returns null when nothing matches exactly (reconciliation is a separate,
- * explicit step — resolution never guesses).
- */
-export function resolveInGltf(address: NeedleAddress, json: GltfJson): GltfResolveResult | null {
-    const searched: Array<readonly [string, string]> = address.type
-        ? [[address.type, collectionKeyForType(address.type)]]
-        : [...STAMPED_COLLECTIONS];
-
-    if (address.id) {
-        for (const [type, key] of searched) {
-            const found = findInCollection(json, key, el => el.extras?.[NEEDLE_ID_KEY] === address.id);
-            if (found) return { type, index: found.index, element: found.element };
-        }
-    }
-    if (address.anchor) {
-        for (const [type, key] of searched) {
-            const found = findInCollection(json, key, el => parseAnchorValue(el.name as string | undefined) === address.anchor);
-            if (found) return { type, index: found.index, element: found.element };
-        }
-    }
-    if (address.namePath?.length && (!address.type || address.type === "node")) {
-        const index = walkGltfNamePath(json, address.namePath);
-        if (index !== null) {
-            const nodes = json["nodes"] as Array<Record<string, unknown>>;
-            return { type: "node", index, element: nodes[index] };
-        }
-    }
-    return null;
-}
-
-/**
- * Resolve an address inside a live scene graph (duck-typed — any three.js).
- * Same order as glTF resolution: id → anchor → namePath.
- */
-export function resolveInGraph(address: NeedleAddress, root: GraphNode): GraphNode | null {
-    if (address.id) {
-        const byId = findInGraph(root, n => n.userData?.[NEEDLE_ID_KEY] === address.id);
-        if (byId) return byId;
-    }
-    if (address.anchor) {
-        const byAnchor = findInGraph(root, n => parseAnchorValue(n.name) === address.anchor);
-        if (byAnchor) return byAnchor;
-    }
-    if (address.namePath?.length) {
-        let current: GraphNode | null = root;
-        for (const segment of address.namePath) {
-            current = current.children?.find(c => (c.name ?? "") === segment) ?? null;
-            if (!current) break;
-        }
-        if (current && current !== root) return current;
-    }
-    return null;
-}
-
-export type ReconcileCandidate = {
-    object: GraphNode;
-    /** 0..1 — heuristic, for ranking and thresholds; 1.0 is reserved for exact resolution */
-    confidence: number;
-    reasons: string[];
-};
-
-/**
- * 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.
- */
-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 candidates: ReconcileCandidate[] = [];
-    collectDescendants(root, (node, namePath) => {
-        if ((node.name ?? "") !== targetName) return;
-        const reasons = [`name matches "${targetName}"`];
-        let confidence = 0.5;
-        if (address.namePath?.length) {
-            const similarity = pathSuffixSimilarity(address.namePath, namePath);
-            confidence += 0.4 * similarity;
-            if (similarity > 0) reasons.push(`path suffix similarity ${(similarity * 100).toFixed(0)}%`);
-        }
-        candidates.push({ object: node, confidence, reasons });
-    });
-    if (candidates.length === 1) {
-        candidates[0].confidence = Math.min(0.95, candidates[0].confidence + 0.1);
-        candidates[0].reasons.push("only candidate with this name");
-    }
-    return candidates.sort((a, b) => b.confidence - a.confidence);
-}
-
-function findInCollection(json: GltfJson, key: string, predicate: (el: Record<string, any>) => boolean): { index: number; element: Record<string, unknown> } | null {
-    const collection = json[key];
-    if (!Array.isArray(collection)) return null;
-    for (let i = 0; i < collection.length; i++) {
-        const element = collection[i];
-        if (element != null && typeof element === "object" && predicate(element)) {
-            return { index: i, element };
-        }
-    }
-    return null;
-}
-
-function walkGltfNamePath(json: GltfJson, namePath: 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) {
-        match = candidates.find(i => ((nodes[i]?.name ?? "") === segment)) ?? null;
-        if (match === null) return null;
-        const children = nodes[match]?.children;
-        candidates = Array.isArray(children) ? children : [];
-    }
-    return match;
-}
-
-function findInGraph(root: GraphNode, predicate: (node: GraphNode) => boolean, visited = new Set<GraphNode>()): GraphNode | null {
-    if (visited.has(root)) return null;
-    visited.add(root);
-    if (predicate(root)) return root;
-    if (!root.children) return null;
-    for (let i = 0; i < root.children.length; i++) {
-        const child = root.children[i];
-        if (child == null) continue;
-        const found = findInGraph(child, predicate, visited);
-        if (found) return found;
-    }
-    return null;
-}
-
-/** 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 {
-    const visited = new Set<GraphNode>();
-    const walk = (node: GraphNode, namePath: string[]) => {
-        if (visited.has(node)) return;
-        visited.add(node);
-        if (node !== root) visit(node, namePath);
-        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(root, []);
-}
-
-/** how much of the expected path's tail matches the actual path's tail (0..1) */
-function pathSuffixSimilarity(expected: string[], actual: string[]): number {
-    let shared = 0;
-    while (
-        shared < expected.length &&
-        shared < actual.length &&
-        expected[expected.length - 1 - shared] === actual[actual.length - 1 - shared]
-    ) {
-        shared++;
-    }
-    return shared / Math.max(expected.length, actual.length);
-}
+import { parseAnchorValue } from "./anchor.js";
+import { collectionKeyForType, GraphNode, NeedleAddress } from "./address.js";
+import { GltfJson, NEEDLE_ID_KEY, STAMPED_COLLECTIONS } from "./gltf.js";
+
+export type GltfResolveResult = {
+    type: string;
+    index: number;
+    element: Record<string, unknown>;
+};
+
+/**
+ * Resolve an address inside glTF JSON. Tries id → anchor → namePath (nodes), in that
+ * order; returns null when nothing matches exactly (reconciliation is a separate,
+ * explicit step — resolution never guesses).
+ */
+export function resolveInGltf(address: NeedleAddress, json: GltfJson): GltfResolveResult | null {
+    const searched: Array<readonly [string, string]> = address.type
+        ? [[address.type, collectionKeyForType(address.type)]]
+        : [...STAMPED_COLLECTIONS];
+
+    if (address.id) {
+        for (const [type, key] of searched) {
+            const found = findInCollection(json, key, el => el.extras?.[NEEDLE_ID_KEY] === address.id);
+            if (found) return { type, index: found.index, element: found.element };
+        }
+    }
+    if (address.anchor) {
+        for (const [type, key] of searched) {
+            const found = findInCollection(json, key, el => parseAnchorValue(el.name as string | undefined) === address.anchor);
+            if (found) return { type, index: found.index, element: found.element };
+        }
+    }
+    if (address.namePath?.length && (!address.type || address.type === "node")) {
+        const index = walkGltfNamePath(json, address.namePath);
+        if (index !== null) {
+            const nodes = json["nodes"] as Array<Record<string, unknown>>;
+            return { type: "node", index, element: nodes[index] };
+        }
+    }
+    return null;
+}
+
+/**
+ * Resolve an address inside a live scene graph (duck-typed — any three.js).
+ * Same order as glTF resolution: id → anchor → namePath.
+ */
+export function resolveInGraph(address: NeedleAddress, root: GraphNode): GraphNode | null {
+    if (address.id) {
+        const byId = findInGraph(root, n => n.userData?.[NEEDLE_ID_KEY] === address.id);
+        if (byId) return byId;
+    }
+    if (address.anchor) {
+        const byAnchor = findInGraph(root, n => parseAnchorValue(n.name) === address.anchor);
+        if (byAnchor) return byAnchor;
+    }
+    if (address.namePath?.length) {
+        let current: GraphNode | null = root;
+        for (const segment of address.namePath) {
+            current = current.children?.find(c => (c.name ?? "") === segment) ?? null;
+            if (!current) break;
+        }
+        if (current && current !== root) return current;
+    }
+    return null;
+}
+
+export type ReconcileCandidate = {
+    object: GraphNode;
+    /** 0..1 — heuristic, for ranking and thresholds; 1.0 is reserved for exact resolution */
+    confidence: number;
+    reasons: string[];
+};
+
+/**
+ * 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.
+ */
+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 candidates: ReconcileCandidate[] = [];
+    collectDescendants(root, (node, namePath) => {
+        if ((node.name ?? "") !== targetName) return;
+        const reasons = [`name matches "${targetName}"`];
+        let confidence = 0.5;
+        if (address.namePath?.length) {
+            const similarity = pathSuffixSimilarity(address.namePath, namePath);
+            confidence += 0.4 * similarity;
+            if (similarity > 0) reasons.push(`path suffix similarity ${(similarity * 100).toFixed(0)}%`);
+        }
+        candidates.push({ object: node, confidence, reasons });
+    });
+    if (candidates.length === 1) {
+        candidates[0].confidence = Math.min(0.95, candidates[0].confidence + 0.1);
+        candidates[0].reasons.push("only candidate with this name");
+    }
+    return candidates.sort((a, b) => b.confidence - a.confidence);
+}
+
+function findInCollection(json: GltfJson, key: string, predicate: (el: Record<string, any>) => boolean): { index: number; element: Record<string, unknown> } | null {
+    const collection = json[key];
+    if (!Array.isArray(collection)) return null;
+    for (let i = 0; i < collection.length; i++) {
+        const element = collection[i];
+        if (element != null && typeof element === "object" && predicate(element)) {
+            return { index: i, element };
+        }
+    }
+    return null;
+}
+
+function walkGltfNamePath(json: GltfJson, namePath: 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) {
+        match = candidates.find(i => ((nodes[i]?.name ?? "") === segment)) ?? null;
+        if (match === null) return null;
+        const children = nodes[match]?.children;
+        candidates = Array.isArray(children) ? children : [];
+    }
+    return match;
+}
+
+function findInGraph(root: GraphNode, predicate: (node: GraphNode) => boolean, visited = new Set<GraphNode>()): GraphNode | null {
+    if (visited.has(root)) return null;
+    visited.add(root);
+    if (predicate(root)) return root;
+    if (!root.children) return null;
+    for (let i = 0; i < root.children.length; i++) {
+        const child = root.children[i];
+        if (child == null) continue;
+        const found = findInGraph(child, predicate, visited);
+        if (found) return found;
+    }
+    return null;
+}
+
+/** 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 {
+    const visited = new Set<GraphNode>();
+    const walk = (node: GraphNode, namePath: string[]) => {
+        if (visited.has(node)) return;
+        visited.add(node);
+        if (node !== root) visit(node, namePath);
+        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(root, []);
+}
+
+/** how much of the expected path's tail matches the actual path's tail (0..1) */
+function pathSuffixSimilarity(expected: string[], actual: string[]): number {
+    let shared = 0;
+    while (
+        shared < expected.length &&
+        shared < actual.length &&
+        expected[expected.length - 1 - shared] === actual[actual.length - 1 - shared]
+    ) {
+        shared++;
+    }
+    return shared / Math.max(expected.length, actual.length);
+}

package/src/uuid.ts

@@ -1,48 +1,48 @@
-import { sha1, toHex } from "./hash.js";
-
-/** RFC 4122 URL namespace — the namespace needle-cloud's `ensureUUID` uses (`uuidv5.URL`). */
-export const UUID_NAMESPACE_URL = "6ba7b811-9dad-11d1-80b4-00c04fd430c8";
-
-/**
- * RFC 4122 version-5 (SHA-1, name-based) UUID. Byte-identical to the `uuid` npm
- * package's `v5(name, namespace)`.
- */
-export function uuidv5(name: string, namespace: string = UUID_NAMESPACE_URL): string {
-    const ns = parseUuidBytes(namespace);
-    const nameBytes = new TextEncoder().encode(name);
-    const input = new Uint8Array(ns.length + nameBytes.length);
-    input.set(ns);
-    input.set(nameBytes, ns.length);
-    const hash = sha1(input).slice(0, 16);
-    hash[6] = (hash[6] & 0x0f) | 0x50; // version 5
-    hash[8] = (hash[8] & 0x3f) | 0x80; // RFC 4122 variant
-    return formatUuid(hash);
-}
-
-/**
- * Random UUID for content that has no source file to be deterministic against
- * (scratch content created in an editor). Uses the platform's crypto when available.
- */
-export function randomUuid(): string {
-    const cryptoObj = globalThis.crypto;
-    if (cryptoObj?.randomUUID) return cryptoObj.randomUUID();
-    const bytes = new Uint8Array(16);
-    if (cryptoObj?.getRandomValues) cryptoObj.getRandomValues(bytes);
-    else for (let i = 0; i < 16; i++) bytes[i] = Math.floor(Math.random() * 256);
-    bytes[6] = (bytes[6] & 0x0f) | 0x40;
-    bytes[8] = (bytes[8] & 0x3f) | 0x80;
-    return formatUuid(bytes);
-}
-
-function parseUuidBytes(uuid: string): Uint8Array {
-    const hex = uuid.replace(/-/g, "");
-    if (hex.length !== 32) throw new Error(`Invalid UUID: ${uuid}`);
-    const bytes = new Uint8Array(16);
-    for (let i = 0; i < 16; i++) bytes[i] = parseInt(hex.substring(i * 2, i * 2 + 2), 16);
-    return bytes;
-}
-
-function formatUuid(bytes: Uint8Array): string {
-    const hex = toHex(bytes);
-    return `${hex.substring(0, 8)}-${hex.substring(8, 12)}-${hex.substring(12, 16)}-${hex.substring(16, 20)}-${hex.substring(20)}`;
-}
+import { sha1, toHex } from "./hash.js";
+
+/** RFC 4122 URL namespace — the namespace needle-cloud's `ensureUUID` uses (`uuidv5.URL`). */
+export const UUID_NAMESPACE_URL = "6ba7b811-9dad-11d1-80b4-00c04fd430c8";
+
+/**
+ * RFC 4122 version-5 (SHA-1, name-based) UUID. Byte-identical to the `uuid` npm
+ * package's `v5(name, namespace)`.
+ */
+export function uuidv5(name: string, namespace: string = UUID_NAMESPACE_URL): string {
+    const ns = parseUuidBytes(namespace);
+    const nameBytes = new TextEncoder().encode(name);
+    const input = new Uint8Array(ns.length + nameBytes.length);
+    input.set(ns);
+    input.set(nameBytes, ns.length);
+    const hash = sha1(input).slice(0, 16);
+    hash[6] = (hash[6] & 0x0f) | 0x50; // version 5
+    hash[8] = (hash[8] & 0x3f) | 0x80; // RFC 4122 variant
+    return formatUuid(hash);
+}
+
+/**
+ * Random UUID for content that has no source file to be deterministic against
+ * (scratch content created in an editor). Uses the platform's crypto when available.
+ */
+export function randomUuid(): string {
+    const cryptoObj = globalThis.crypto;
+    if (cryptoObj?.randomUUID) return cryptoObj.randomUUID();
+    const bytes = new Uint8Array(16);
+    if (cryptoObj?.getRandomValues) cryptoObj.getRandomValues(bytes);
+    else for (let i = 0; i < 16; i++) bytes[i] = Math.floor(Math.random() * 256);
+    bytes[6] = (bytes[6] & 0x0f) | 0x40;
+    bytes[8] = (bytes[8] & 0x3f) | 0x80;
+    return formatUuid(bytes);
+}
+
+function parseUuidBytes(uuid: string): Uint8Array {
+    const hex = uuid.replace(/-/g, "");
+    if (hex.length !== 32) throw new Error(`Invalid UUID: ${uuid}`);
+    const bytes = new Uint8Array(16);
+    for (let i = 0; i < 16; i++) bytes[i] = parseInt(hex.substring(i * 2, i * 2 + 2), 16);
+    return bytes;
+}
+
+function formatUuid(bytes: Uint8Array): string {
+    const hex = toHex(bytes);
+    return `${hex.substring(0, 8)}-${hex.substring(8, 12)}-${hex.substring(12, 16)}-${hex.substring(16, 20)}-${hex.substring(20)}`;
+}