@needle-tools/addressing 0.3.1 → 0.3.3

package/dist/resolve.js

@@ -0,0 +1,288 @@
+import { parseAnchorValue } from "./anchor.js";
+import { collectionKeyForType } from "./address.js";
+import { NEEDLE_ID_KEY, STAMPED_COLLECTIONS } from "./gltf.js";
+/**
+ * Resolve an address inside glTF JSON. Same ladder as the live graph —
+ * **anchor → id → namePath** (nodes) — with the anchor winning only when it matches
+ * exactly one element. Returns null when nothing matches exactly (reconciliation is a
+ * separate, explicit step — resolution never guesses).
+ */
+export function resolveInGltf(address, json, options) {
+    const report = options?.report;
+    const searched = address.type
+        ? [[address.type, collectionKeyForType(address.type)]]
+        : [...STAMPED_COLLECTIONS];
+    let byAnchor = null;
+    if (address.anchor) {
+        const matches = [];
+        for (const [type, key] of searched) {
+            for (const found of collectInJsonCollection(json, key, el => parseAnchorValue(el.name) === address.anchor)) {
+                matches.push({ type, index: found.index, element: found.element });
+                if (matches.length > 1 && !report)
+                    break;
+            }
+            if (matches.length > 1 && !report)
+                break;
+        }
+        if (matches.length === 1)
+            byAnchor = matches[0];
+        else if (matches.length > 1)
+            report?.({ kind: "ambiguous-anchor", anchor: address.anchor, count: matches.length });
+    }
+    if (byAnchor && !report)
+        return byAnchor;
+    let byId = null;
+    if (address.id) {
+        for (const [type, key] of searched) {
+            const found = findInCollection(json, key, el => el.extras?.[NEEDLE_ID_KEY] === address.id);
+            if (found) {
+                byId = { type, index: found.index, element: found.element };
+                break;
+            }
+        }
+    }
+    if (byAnchor) {
+        if (byId && (byId.type !== byAnchor.type || byId.index !== byAnchor.index)) {
+            report?.({ kind: "conflict", preferred: "anchor", other: "id" });
+        }
+        return byAnchor;
+    }
+    if (byId)
+        return byId;
+    if (address.namePath?.length && (!address.type || address.type === "node")) {
+        const index = walkGltfNamePath(json, address.namePath);
+        if (index !== null) {
+            const nodes = json["nodes"];
+            return { type: "node", index, element: nodes[index] };
+        }
+    }
+    return null;
+}
+/**
+ * Resolve an address inside a live scene graph (duck-typed — any three.js).
+ *
+ * Ladder: **anchor → id → namePath**. The anchor comes first because it is a deliberate,
+ * human-authored declaration, while an id may be a derived value whose basis shifted when
+ * the content changed. It only wins when it resolves UNIQUELY: anchors are labels and may
+ * legally repeat, and an ambiguous label must never outrank an exact key.
+ */
+export function resolveInGraph(address, root, options) {
+    const report = options?.report;
+    let byAnchor = null;
+    if (address.anchor) {
+        // without a reporter, stop at two — "exactly one" vs "more than one" is all the
+        // ladder needs, and the count only matters for the message
+        const matches = collectInGraph(root, n => parseAnchorValue(n.name) === address.anchor, report ? Infinity : 2);
+        if (matches.length === 1)
+            byAnchor = matches[0];
+        else if (matches.length > 1)
+            report?.({ kind: "ambiguous-anchor", anchor: address.anchor, count: matches.length });
+    }
+    // fast path: nothing left to learn unless the caller wants the disagreement reported
+    if (byAnchor && !report)
+        return byAnchor;
+    let byId = null;
+    if (address.id)
+        byId = findInGraph(root, n => n.userData?.[NEEDLE_ID_KEY] === address.id);
+    if (byAnchor) {
+        if (byId && byId !== byAnchor)
+            report?.({ kind: "conflict", preferred: "anchor", other: "id" });
+        return byAnchor;
+    }
+    if (byId)
+        return byId;
+    if (address.namePath?.length) {
+        let current = 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;
+}
+/**
+ * Resolve an address against a FLAT collection of live elements — materials, textures and
+ * anything else that carries a name and `userData` but is not part of the scene graph.
+ *
+ * Same ladder as the graph, minus `namePath` (there is no hierarchy to walk) plus `name`
+ * as the final rung, since a flat collection has no positional fallback. This exists so
+ * every element type resolves through ONE implementation: materials previously had their
+ * own ladders, could not be anchored at all, and disagreed with each other about whether a
+ * name match had to be unique.
+ */
+export function resolveInCollection(address, elements, options) {
+    const report = options?.report;
+    let byAnchor = null;
+    if (address.anchor) {
+        const matches = elements.filter(e => parseAnchorValue(e.name) === address.anchor);
+        if (matches.length === 1)
+            byAnchor = matches[0];
+        else if (matches.length > 1)
+            report?.({ kind: "ambiguous-anchor", anchor: address.anchor, count: matches.length });
+    }
+    if (byAnchor && !report)
+        return byAnchor;
+    const byId = address.id ? elements.find(e => e.userData?.[NEEDLE_ID_KEY] === address.id) ?? null : null;
+    if (byAnchor) {
+        if (byId && byId !== byAnchor)
+            report?.({ kind: "conflict", preferred: "anchor", other: "id" });
+        return byAnchor;
+    }
+    if (byId)
+        return byId;
+    if (address.name) {
+        const named = elements.filter(e => e.name === address.name);
+        if (named.length === 1)
+            return named[0];
+        if (named.length > 1)
+            report?.({ kind: "ambiguous-name", name: address.name, count: named.length });
+    }
+    return null;
+}
+/**
+ * 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, root) {
+    if (!address.name && !address.namePath?.length)
+        return [];
+    const targetName = address.name ?? address.namePath[address.namePath.length - 1];
+    const candidates = [];
+    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);
+}
+/** every element of one glTF collection matching `predicate` */
+function collectInJsonCollection(json, key, predicate) {
+    const collection = json[key];
+    if (!Array.isArray(collection))
+        return [];
+    const found = [];
+    for (let i = 0; i < collection.length; i++) {
+        const element = collection[i];
+        if (element != null && typeof element === "object" && predicate(element)) {
+            found.push({ index: i, element });
+        }
+    }
+    return found;
+}
+function findInCollection(json, key, predicate) {
+    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, namePath) {
+    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 = scenes.flatMap(s => (Array.isArray(s?.nodes) ? s.nodes : []));
+    let match = 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;
+}
+/** every node matching `predicate`, stopping once `limit` are found (cycle-safe) */
+function collectInGraph(root, predicate, limit) {
+    const found = [];
+    const visited = new Set();
+    const walk = (node) => {
+        if (found.length >= limit || visited.has(node))
+            return;
+        visited.add(node);
+        if (predicate(node)) {
+            found.push(node);
+            if (found.length >= limit)
+                return;
+        }
+        if (!node.children)
+            return;
+        for (let i = 0; i < node.children.length; i++) {
+            const child = node.children[i];
+            if (child != null)
+                walk(child);
+        }
+    };
+    walk(root);
+    return found;
+}
+function findInGraph(root, predicate, visited = new Set()) {
+    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, visit) {
+    const visited = new Set();
+    const walk = (node, namePath) => {
+        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, actual) {
+    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/dist/uuid.d.ts

@@ -0,0 +1,12 @@
+/** RFC 4122 URL namespace — the namespace needle-cloud's `ensureUUID` uses (`uuidv5.URL`). */
+export declare 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 declare function uuidv5(name: string, namespace?: string): string;
+/**
+ * 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 declare function randomUuid(): string;

package/dist/uuid.js

@@ -0,0 +1,49 @@
+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, namespace = UUID_NAMESPACE_URL) {
+    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() {
+    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) {
+    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) {
+    const hex = toHex(bytes);
+    return `${hex.substring(0, 8)}-${hex.substring(8, 12)}-${hex.substring(12, 16)}-${hex.substring(16, 20)}-${hex.substring(20)}`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@needle-tools/addressing",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "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",
@@ -8,16 +8,19 @@
   "exports": {
     ".": {
       "types": "./src/index.ts",
+      "node": "./dist/index.js",
       "default": "./src/index.ts"
     }
   },
   "files": [
+    "dist",
     "src",
     "Readme.md"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "test": "vitest run"
+    "test": "vitest run",
+    "prepack": "npm run build"
   },
   "author": {
     "name": "Needle",

package/src/address.ts

@@ -42,7 +42,11 @@ export function createGltfElementAddress(json: GltfJson, type: StampedElementTyp
     if (id) address.id = id;
     const anchor = parseAnchorValue(name);
     if (anchor) address.anchor = anchor;
-    if (name !== undefined) address.name = name;
+    // an empty name is non-information: resolution never reads `name` (id → anchor →
+    // namePath) and reconciliation falls back to the last namePath segment ("" again).
+    // NOTE: empty namePath SEGMENTS are load-bearing (positional child-walk) — only the
+    // standalone `name` field is dropped when empty.
+    if (name) address.name = name;
     if (type === "node") {
         const path = gltfNodeNamePath(json, index);
         if (path) address.namePath = path;
@@ -60,7 +64,8 @@ export function createObjectAddress(root: GraphNode, target: GraphNode): NeedleA
     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;
+    // empty name dropped — see createGltfElementAddress; namePath segments stay verbatim
+    if (target.name) address.name = target.name;
     address.namePath = path.map(n => n.name ?? "");
     return address;
 }

package/src/anchor.ts

@@ -37,12 +37,27 @@ export function parseAnchor(rawName: string | null | undefined): ParsedAnchor |
     const lower = trimmed.toLowerCase();
     for (const marker of byLengthDescending(ANCHOR_MARKERS)) {
         if (!lower.endsWith(marker)) continue;
-        const value = trimmed.substring(0, trimmed.length - marker.length).trim();
+        const value = normalizeName(trimmed.substring(0, trimmed.length - marker.length));
         return value.length > 0 ? { marker, value } : null;
     }
     return null;
 }
 
+/**
+ * Names 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 a
+ * 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 are one name.
+ *
+ * Exported because id derivation applies the SAME rule to unanchored names (see
+ * {@link import("./id.js").idNameOf}) — one normalization, one change point.
+ */
+export function normalizeName(value: string): string {
+    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.

package/src/gltf.ts

@@ -1,4 +1,4 @@
-import { computeElementId } from "./id.js";
+import { computeElementId, idNameOf } from "./id.js";
 
 /** The glTF `extras` key carrying the persistent id. */
 export const NEEDLE_ID_KEY = "needle-id";
@@ -64,14 +64,16 @@ export function ensureIds(json: GltfJson, options?: EnsureIdsOptions): EnsureIds
         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
+        // 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 occurrence = occurrences.get(name) ?? 0;
-            occurrences.set(name, occurrence + 1);
+            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);

package/src/id.ts

@@ -1,45 +1,61 @@
-import { parseAnchorValue } from "./anchor.js";
+import { normalizeName, parseAnchor } from "./anchor.js";
 import { uuidv5 } from "./uuid.js";
 
 /**
- * The deterministic needle-id of a glTF element.
+ * The name an id is derived FROM: the anchor marker removed (if any) and space/underscore
+ * runs collapsed.
  *
- * - 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.
+ * 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 {
-    const anchor = parseAnchorValue(name);
-    const str = anchor !== null
-        ? `${type}-${anchor}`
-        : `${type}-${name ? name : ""}-${occurrence}${baseHash ? `-${baseHash}` : ""}`;
-    return uuidv5(str);
+    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 = normalizedName(elements[index]);
+    const name = idNameOf(elements[index]?.name as string | null | undefined);
     let occurrence = 0;
     for (let i = 0; i < index; i++) {
-        if (normalizedName(elements[i]) === name) occurrence++;
+        if (idNameOf(elements[i]?.name as string | null | undefined) === name) occurrence++;
     }
     return occurrence;
 }
-
-function normalizedName(element: { name?: unknown } | null | undefined): string {
-    return typeof element?.name === "string" ? element.name : "";
-}

package/src/index.ts

@@ -21,9 +21,14 @@ export {
 } 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";