@needle-tools/addressing 0.3.2 → 0.3.3

package/src/gltf.ts

@@ -1,89 +1,91 @@
-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;
-}
+import { computeElementId, idNameOf } 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. Grouping is by the DERIVATION name
+        // (anchor marker stripped, normalized), matching occurrenceOfName.
+        const occurrences = new Map<string, number>();
+        for (let index = 0; index < elements.length; index++) {
+            const element = elements[index] as GltfElement;
+            if (element == null || typeof element !== "object") continue;
+            const name = typeof element.name === "string" ? element.name : "";
+            const group = idNameOf(name);
+            const occurrence = occurrences.get(group) ?? 0;
+            occurrences.set(group, occurrence + 1);
+            element.extras ??= {};
+            if (element.extras[NEEDLE_ID_KEY] === undefined) {
+                element.extras[NEEDLE_ID_KEY] = computeElementId(type, name, occurrence, baseHash);
+                assigned++;
+            }
+        }
+    }
+    return { baseHash, assigned };
+}
+
+/** Read an element's needle-id without computing anything. */
+export function getElementId(element: GltfElement | null | undefined): string | null {
+    const id = element?.extras?.[NEEDLE_ID_KEY];
+    return typeof id === "string" ? id : null;
+}

package/src/hash.ts

@@ -1,58 +1,58 @@
-/**
- * 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;
-}
+/**
+ * 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,45 +1,61 @@
-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 : "";
-}
+import { normalizeName, parseAnchor } from "./anchor.js";
+import { uuidv5 } from "./uuid.js";
+
+/**
+ * The name an id is derived FROM: the anchor marker removed (if any) and space/underscore
+ * runs collapsed.
+ *
+ * The marker is stripped because **ids are minted as if no anchor existed** — an anchor is
+ * a LABEL, not an identity, and the two must be able to change independently. Both halves
+ * of that are load-bearing:
+ * - stripping the marker means ADDING or REMOVING `#needle` leaves the id untouched (under
+ *   the previous rule, anchoring an object CHANGED its id — so the very act recommended for
+ *   making something stable orphaned every edit already addressed to it);
+ * - {@link occurrenceOfName} groups on this same value, so anchoring ONE of two `Door`s
+ *   does not shift the OTHER one's occurrence.
+ *
+ * Note what is decoupled: the id is independent of the anchor MARKER, not of the NAME.
+ * Renaming `Door #needle` → `Entrance #needle` still changes a DERIVED id; a STAMPED id is
+ * unaffected, since existing ids are never overwritten.
+ */
+export function idNameOf(name: string | null | undefined): string {
+    if (typeof name !== "string") return "";
+    // an anchor's value is already marker-stripped and normalized
+    return parseAnchor(name)?.value ?? normalizeName(name);
+}
+
+/**
+ * The deterministic needle-id of a glTF element:
+ * `uuidv5("<type>-<idName>-<occurrence>[-<baseHash>]")`, where `idName` is the name with
+ * any anchor marker removed ({@link idNameOf}) and `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 {
+    return uuidv5(`${type}-${idNameOf(name)}-${occurrence}${baseHash ? `-${baseHash}` : ""}`);
+}
+
+/**
+ * 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.
+ *
+ * Grouping is by {@link idNameOf}, so an anchored element counts in the same group as its
+ * unanchored namesakes.
+ */
+export function occurrenceOfName(elements: ReadonlyArray<{ name?: unknown } | null | undefined>, index: number): number {
+    const name = idNameOf(elements[index]?.name as string | null | undefined);
+    let occurrence = 0;
+    for (let i = 0; i < index; i++) {
+        if (idNameOf(elements[i]?.name as string | null | undefined) === name) occurrence++;
+    }
+    return occurrence;
+}

package/src/index.ts

@@ -1,29 +1,34 @@
-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";
+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,
+    resolveInCollection,
+    resolveInGltf,
+    resolveInGraph,
+    type AddressableElement,
+    type GltfResolveResult,
+    type ReconcileCandidate,
+    type ResolutionIssue,
+    type ResolutionRung,
+    type ResolveOptions,
+} from "./resolve.js";
+export { randomUuid, uuidv5, UUID_NAMESPACE_URL } from "./uuid.js";